feat(hub): usage fact ledger for run-scoped cost attribution (ADR-0026)

Replace the single-scalar cost model on AgentRun with an append-only
UsageFact ledger. One AgentRun owns zero or more UsageFact rows; each
records one billable consumption event (model completion, external
capability, or tool proxy) with its own provider/model/tokens/quantity/
cost. AgentRun.costUsd/inputTokens/outputTokens become a derived rollup
cache.

This unblocks external capabilities (PDF->MD bundle, audio/video->text)
that bill in non-token units (pages, seconds) through a different
provider than the main agent loop, without per-capability schema changes
or nested AgentRuns (which would pollute lock/admission/session
semantics).

Contract:
- spec/Spec/System/Agent/Usage.lean pins UsageFact, UsageFactKind,
  CostSource and three invariants: append-only; belongs to one run,
  never holds a lock; missing cost != zero (ADR-0022).
- ADR-0026 records the decision, the rejected nested-Run alternative,
  the rollup cache strategy, and the deferred capability registry /
  pricebook / post-hoc correction flows.

Schema:
- UsageFact model with indexes on (runId, occurredAt), (runId, kind),
  (provider, model, occurredAt), (capabilityId, occurredAt).
- Migration backfills one synthetic model_completion fact per existing
  run with recorded cost/tokens (correlationId = runId marks backfill);
  truly unrecorded runs stay runsWithoutCost per ADR-0022.

Write path (trigger finish):
- Write the UsageFact first, then mirror it onto AgentRun as two
  separate statements (not one transaction). The fact is the truth so it
  goes first; the cache is derived so it goes second. A crash between
  them leaves the cache stale but the usage service re-reads facts
  directly, so this is recoverable; the reverse order would lose the
  truth. Separate statements also avoid an AgentRun row lock held across
  the insert's FK ShareLock, which deadlocked concurrent workspace
  teardown under the Organization->Project->AgentRun->UsageFact cascade.

Read paths:
- org/usage.ts aggregates from UsageFact, ignoring the AgentRun cache.
- slash /usage buckets by (fact.provider, fact.model); a run with a
  main loop + an external call lands in two buckets.
- session detail exposes usageFacts[] + costSource for future per-run
  cost-breakdown UI.

Tests:
- usage.test.ts: 6 integration tests pin fact aggregation, missing-cost-
  !=-zero, multi-fact-per-run, empty-run, project-level, empty-org.
- trigger.test.ts: existing /usage assertion ($0.0023,
  openrouter / mock-model) passes on the fact path.
- feishu-reactions mock prisma gains usageFact.create.

docs/adr/0018-agent-execution-surface-bounded-by-workspace.md

@@ -123,15 +123,23 @@ The boundary is enforced by the Claude Code SDK's built-in sandbox
   workspace or service-user config from widening tools, hooks, MCP servers, or
   sandbox paths.
 - Agent skills are Organization-scoped runtime configuration, not Hub release
-  assets. A controlled host-console installer imports each version into a
-  content-addressed persistent store and records its digest in PostgreSQL. A
-  role selects enabled Organization skills alongside its model, system prompt
-  and tool allowlist. Each run copies only those selected immutable versions
-  into a run-scoped plugin outside the project workspace; the sandbox exposes
-  that snapshot read-only and deletes it after the run. SDK-bundled skills and
-  filesystem setting sources remain disabled, so project `.claude` content
-  cannot register skills or widen tools. Requested skill versions are recorded
-  on `run.created`; SDK initialization remains authoritative loading evidence.
+  assets. Skill content is imported into a content-addressed persistent store
+  through a shared ingestion pipeline (`importSkillDirectory` for host-console
+  CLI, `importSkillFromFiles` for org-admin web surface) that enforces the same
+  safety checks: `SKILL.md` manifest required, 512-file / 16-byte limits,
+  symlink rejection, SHA-256 content addressing. The web surface
+  (`OrganizationAgentConfiguration.installSkillFromFiles`) writes to the same
+  store as the host-console CLI (`installSkill`); both flow through
+  `commitSkillContent` for deduplication and atomic rename into
+  `versions/<digest>/`. Org-admin authentication gates the web surface; the
+  content-addressed store remains platform-controlled. A role selects enabled
+  Organization skills alongside its model, system prompt and tool allowlist.
+  Each run copies only those selected immutable versions into a run-scoped
+  plugin outside the project workspace; the sandbox exposes that snapshot
+  read-only and deletes it after the run. SDK-bundled skills and filesystem
+  setting sources remain disabled, so project `.claude` content cannot register
+  skills or widen tools. Requested skill versions are recorded on
+  `run.created`; SDK initialization remains authoritative loading evidence.
 - Network: open (see Open Questions).
 
 `bypassPermissions` is kept (headless server — no interactive prompts); the

docs/adr/0026-usage-fact-ledger.md

@@ -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.

hub/.env.example

@@ -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=""

hub/admin-web/src/lib/api.ts

@@ -226,6 +226,50 @@ export interface CapacityPolicyView {
 	dimensions: CapacityDimensionRow[];
 }
 
+export interface AgentRoleRow {
+	id: string;
+	roleId: string;
+	label: string;
+	defaultModel: string | null;
+	systemPrompt: string | null;
+	tools: readonly string[] | null;
+	sortOrder: number;
+	isDefault: boolean;
+	disabledAt: string | null;
+	createdAt: string;
+	updatedAt: string;
+	skillNames: readonly string[];
+}
+
+export interface AgentSkillRow {
+	id: string;
+	name: string;
+	version: string;
+	description: string | null;
+	contentDigest: string;
+	disabledAt: string | null;
+	createdAt: string;
+	updatedAt: string;
+	boundRoleIds: readonly string[];
+}
+
+export interface SkillFileEntry {
+	path: string;
+	content: string;
+}
+
+export interface InstalledSkillResult {
+	id: string;
+	name: string;
+	contentDigest: string;
+}
+
+export interface AgentModelRow {
+	id: string;
+	label: string;
+	toolCapable: boolean;
+}
+
 // --- API ---
 
 export const api = {
@@ -261,8 +305,7 @@ export const api = {
 		post(`${orgBase(slug)}/teams/${teamId}/members/${userId}/revoke`),
 
 	explorer: (slug: string) => get(`${orgBase(slug)}/explorer`) as Promise<ExplorerData>,
-	myProjects: (slug: string) =>
-		get(`${orgBase(slug)}/my-projects`) as Promise<{ projects: ExplorerProject[] }>,
+	myProjects: (slug: string) => get(`${orgBase(slug)}/my-projects`) as Promise<{ projects: ExplorerProject[] }>,
 	createFolder: (slug: string, body: { name: string; parentId?: string; sortKey?: string }) =>
 		post(`${orgBase(slug)}/folders`, body) as Promise<{
 			id: string;
@@ -338,8 +381,33 @@ export const api = {
 	disableFeishuApplication: (slug: string) =>
 		del(`${orgBase(slug)}/feishu-application-connection`) as Promise<FeishuApplicationConnection>,
 
-	capacityPolicy: (slug: string) =>
-		get(`${orgBase(slug)}/capacity-policy`) as Promise<CapacityPolicyView>,
+	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>,
+
+	agentRoles: (slug: string) => get(`${orgBase(slug)}/agent-roles`) as Promise<{ roles: AgentRoleRow[] }>,
+	upsertAgentRole: (
+		slug: string,
+		roleId: string,
+		body: {
+			label: string;
+			defaultModel?: string | null;
+			systemPrompt?: string | null;
+			tools?: readonly string[] | null;
+			sortOrder?: number;
+			isDefault?: boolean;
+		},
+	) => put(`${orgBase(slug)}/agent-roles/${encodeURIComponent(roleId)}`, body) as Promise<AgentRoleRow>,
+	setAgentRoleSkills: (slug: string, roleId: string, skillNames: readonly string[]) =>
+		put(`${orgBase(slug)}/agent-roles/${encodeURIComponent(roleId)}/skills`, { skillNames }) as Promise<{
+			skillNames: string[];
+		}>,
+	agentSkills: (slug: string) => get(`${orgBase(slug)}/agent-skills`) as Promise<{ skills: AgentSkillRow[] }>,
+	agentSkillFiles: (slug: string, name: string) =>
+		get(`${orgBase(slug)}/agent-skills/${encodeURIComponent(name)}/files`) as Promise<{ files: SkillFileEntry[] }>,
+	installAgentSkill: (slug: string, name: string, body: { version: string; files: readonly SkillFileEntry[] }) =>
+		put(`${orgBase(slug)}/agent-skills/${encodeURIComponent(name)}`, body) as Promise<InstalledSkillResult>,
+	patchAgentSkill: (slug: string, name: string, body: { description?: string; disabled?: boolean }) =>
+		patch(`${orgBase(slug)}/agent-skills/${encodeURIComponent(name)}`, body) as Promise<{ disabled?: boolean; updated?: boolean }>,
+	agentModels: (slug: string) => get(`${orgBase(slug)}/agent-models`) as Promise<{ models: AgentModelRow[] }>,
 };

hub/admin-web/src/lib/components/FolderNode.svelte

@@ -8,6 +8,8 @@
 		folders,
 		projects,
 		slug,
+		onCreateFolder,
+		onCreateProject,
 	}: {
 		folder: ExplorerFolder;
 		folders: ExplorerFolder[];
@@ -19,17 +21,16 @@
 			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)}
-	>
+	<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" />
@@ -40,9 +41,38 @@
 				<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}
+	</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>

hub/admin-web/src/lib/components/FolderTree.svelte

@@ -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));
@@ -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>

hub/admin-web/src/lib/components/Icon.svelte

@@ -15,9 +15,13 @@
 			| 'logout'
 			| 'org'
 			| 'chevron'
+			| 'arrow-left'
 			| 'folder'
 			| 'file'
-			| 'check';
+			| 'folder-plus'
+			| 'file-plus'
+			| 'check'
+			| 'roles';
 		class?: string;
 	} = $props();
 </script>
@@ -100,6 +104,10 @@
 	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
 		<path stroke-linecap="round" stroke-linejoin="round" d="M8.25 4.5l7.5 7.5-7.5 7.5" />
 	</svg>
+{:else if name === 'arrow-left'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path stroke-linecap="round" stroke-linejoin="round" d="M10.5 19.5L3 12m0 0l7.5-7.5M3 12h18" />
+	</svg>
 {:else if name === 'folder'}
 	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
 		<path
@@ -116,8 +124,32 @@
 			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" />
 	</svg>
+{:else if name === 'roles'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M9.813 15.904L9 18.75l-.813-2.846a4.5 4.5 0 00-3.09-3.09L2.25 12l2.847-.813a4.5 4.5 0 003.09-3.09L9 5.25l.813 2.846a4.5 4.5 0 003.09 3.09L15.75 12l-2.847.813a4.5 4.5 0 00-3.09 3.09zM18.259 8.715L18 9.75l-.259-1.035a3.375 3.375 0 00-2.456-2.456L14.25 6l1.035-.259a3.375 3.375 0 002.456-2.456L18 2.25l.259 1.035a3.375 3.375 0 002.456 2.456L21.75 6l-1.035.259a3.375 3.375 0 00-2.456 2.456zM16.894 20.567L16.5 21.75l-.394-1.183a2.25 2.25 0 00-1.423-1.423L13.5 18.75l1.183-.394a2.25 2.25 0 001.423-1.423l.394-1.183.394 1.183a2.25 2.25 0 001.423 1.423l1.183.394-1.183.394a2.25 2.25 0 00-1.423 1.423z"
+		/>
+	</svg>
 {/if}

hub/admin-web/src/lib/components/RoleCard.svelte

@@ -0,0 +1,208 @@
+<script lang="ts">
+	import { Checkbox, Label } from 'bits-ui';
+	import type { AgentRoleRow, AgentModelRow, AgentSkillRow } from '$lib/api';
+	import { api } from '$lib/api';
+	import { fmtDate } from '$lib/format';
+	import { TOOL_OPTIONS } from '$lib/constants';
+	import SelectField from '$lib/components/SelectField.svelte';
+	import CheckboxControl from '$lib/components/CheckboxControl.svelte';
+	import Icon from '$lib/components/Icon.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	let {
+		r,
+		models,
+		skills,
+		slug,
+		onupdated,
+		onskillschanged,
+	}: {
+		r: AgentRoleRow;
+		models: AgentModelRow[];
+		skills: AgentSkillRow[];
+		slug: string;
+		onupdated: (updated: AgentRoleRow) => void;
+		onskillschanged: (roleId: string, skillNames: string[]) => void;
+	} = $props();
+
+	const initial = {
+		label: r.label,
+		defaultModel: r.defaultModel ?? '',
+		systemPrompt: r.systemPrompt ?? '',
+		unrestricted: r.tools === null,
+		tools: r.tools ?? [],
+		sortOrder: String(r.sortOrder),
+		isDefault: r.isDefault,
+		skillNames: r.skillNames,
+	};
+	let label = $state(initial.label);
+	let defaultModel = $state(initial.defaultModel);
+	let systemPrompt = $state(initial.systemPrompt);
+	let unrestricted = $state(initial.unrestricted);
+	let selectedTools = $state<string[]>([...initial.tools]);
+	let sortOrder = $state(initial.sortOrder);
+	let isDefault = $state(initial.isDefault);
+	let selectedSkills = $state<string[]>([...initial.skillNames]);
+	let saving = $state(false);
+
+	const groupedTools = TOOL_OPTIONS.reduce(
+		(acc, t) => {
+			(acc[t.group] ??= []).push(t);
+			return acc;
+		},
+		{} as Record<string, typeof TOOL_OPTIONS>,
+	);
+
+	const modelItems = $derived([
+		{ value: '', label: '（使用平台默认模型）' },
+		...models.map((m) => ({ value: m.id, label: `${m.label}（${m.id}）` })),
+	]);
+
+	const skillItems = $derived(skills.map((s) => ({ value: s.name, label: s.name })));
+
+	function skillsDirty(): boolean {
+		const a = [...selectedSkills].sort();
+		const b = [...r.skillNames].sort();
+		return a.length !== b.length || a.some((v, i) => v !== b[i]);
+	}
+
+	async function save() {
+		const trimmedLabel = label.trim();
+		if (trimmedLabel === '') {
+			toastError('显示名不能为空');
+			return;
+		}
+		const order = Number(sortOrder);
+		if (sortKeyDirty() && (!Number.isSafeInteger(order) || order < 0)) {
+			toastError('排序必须为非负整数');
+			return;
+		}
+		saving = true;
+		const tools = unrestricted ? null : selectedTools;
+		try {
+			const updated = await api.upsertAgentRole(slug, r.roleId, {
+				label: trimmedLabel,
+				defaultModel: defaultModel === '' ? null : defaultModel,
+				systemPrompt: systemPrompt === '' ? null : systemPrompt,
+				tools,
+				...(sortKeyDirty() ? { sortOrder: order } : {}),
+				isDefault,
+			});
+			onupdated(updated);
+			if (skillsDirty()) {
+				const res = await api.setAgentRoleSkills(slug, r.roleId, selectedSkills);
+				selectedSkills = [...res.skillNames];
+				onskillschanged(r.roleId, res.skillNames);
+			}
+			toastSuccess('角色已保存');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			saving = false;
+		}
+	}
+
+	function sortKeyDirty(): boolean {
+		return Number(sortOrder) !== r.sortOrder;
+	}
+</script>
+
+<div class="saas-card-pad">
+	<div class="mb-4 flex flex-wrap items-center gap-2">
+		<span class="saas-badge-primary font-mono">/{r.roleId}</span>
+		<span class="text-sm text-surface-700">{label || r.label}</span>
+		{#if r.isDefault}
+			<span class="saas-badge-success">默认</span>
+		{/if}
+	</div>
+
+	<div class="grid grid-cols-1 gap-4 md:grid-cols-2">
+		<div>
+			<Label.Root for="role-label-{r.id}" class="saas-label">显示名</Label.Root>
+			<input id="role-label-{r.id}" class="saas-input" bind:value={label} />
+		</div>
+		<div>
+			<Label.Root for="role-sort-{r.id}" class="saas-label">排序</Label.Root>
+			<input id="role-sort-{r.id}" class="saas-input" type="number" min="0" bind:value={sortOrder} />
+		</div>
+	</div>
+
+	<div class="mt-4">
+		<p class="saas-label">默认模型</p>
+		<SelectField items={modelItems} bind:value={defaultModel} />
+	</div>
+
+	<div class="mt-4">
+		<span class="saas-label">工具白名单</span>
+		<label class="mb-3 flex cursor-pointer items-center gap-2 border border-surface-300 bg-surface-100 px-3 py-2">
+			<CheckboxControl bind:checked={unrestricted} />
+			<span class="text-sm">不限（使用全部注册工具）</span>
+		</label>
+		<div class="space-y-3 {unrestricted ? 'pointer-events-none opacity-40' : ''}">
+			<Checkbox.Group bind:value={selectedTools} disabled={unrestricted}>
+				{#each Object.entries(groupedTools) as [group, tools]}
+					<div>
+						<p class="mb-1.5 text-xs font-semibold uppercase tracking-wide text-surface-600">{group}</p>
+						<div class="grid grid-cols-1 gap-1.5 sm:grid-cols-2">
+							{#each tools as t}
+								<label class="flex cursor-pointer items-center gap-2 px-2 py-1.5 text-sm hover:bg-surface-100">
+									<Checkbox.Root class="saas-checkbox" value={t.id} id={`tool-${r.id}-${t.id}`}>
+										{#snippet children({ checked })}
+											{#if checked}
+												<Icon name="check" class="h-3.5 w-3.5" />
+											{/if}
+										{/snippet}
+									</Checkbox.Root>
+									<span>{t.label}</span>
+								</label>
+							{/each}
+						</div>
+					</div>
+				{/each}
+			</Checkbox.Group>
+		</div>
+	</div>
+
+	<div class="mt-4">
+		<span class="saas-label">技能绑定</span>
+		{#if skills.length === 0}
+			<p class="text-sm text-surface-600">组织内暂无已安装技能。技能通过 CLI / seed 安装（ADR-0018）。</p>
+		{:else}
+			<div class="grid grid-cols-1 gap-1.5 sm:grid-cols-2">
+				{#each skillItems as s}
+					<label class="flex cursor-pointer items-center gap-2 px-2 py-1.5 text-sm hover:bg-surface-100">
+						<CheckboxControl
+							checked={selectedSkills.includes(s.value)}
+							onchange={(checked) => {
+								selectedSkills = checked ? [...selectedSkills, s.value] : selectedSkills.filter((x) => x !== s.value);
+							}}
+						/>
+						<span class="font-mono text-xs">{s.label}</span>
+					</label>
+				{/each}
+			</div>
+		{/if}
+	</div>
+
+	<div class="mt-4">
+		<Label.Root for="role-prompt-{r.id}" class="saas-label">系统提示词</Label.Root>
+		<textarea
+			id="role-prompt-{r.id}"
+			class="saas-textarea"
+			rows="4"
+			placeholder="系统提示词（可选）。会话开始时注入，定义智能体人格/指令。"
+			bind:value={systemPrompt}></textarea>
+	</div>
+
+	<div class="mt-4 flex flex-wrap items-center gap-3 border-t border-surface-100 pt-4">
+		<label class="flex cursor-pointer items-center gap-2">
+			<CheckboxControl bind:checked={isDefault} />
+			<span class="text-sm">设为组织默认角色</span>
+		</label>
+		<span class="text-xs text-surface-600">更新于 {fmtDate(r.updatedAt)}</span>
+		<div class="flex-1"></div>
+		<button class="saas-btn-primary" onclick={save} disabled={saving}>
+			{saving ? '保存中…' : '保存'}
+		</button>
+	</div>
+</div>

hub/admin-web/src/lib/components/SkillEditor.svelte

@@ -0,0 +1,305 @@
+<script lang="ts">
+	import type { AgentSkillRow, SkillFileEntry } from '$lib/api';
+	import { api } from '$lib/api';
+	import { fmtDate } from '$lib/format';
+	import Icon from '$lib/components/Icon.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	let {
+		slug,
+		skill,
+		oninstalled,
+		ondisabled,
+	}: {
+		slug: string;
+		skill: AgentSkillRow;
+		oninstalled: (result: { id: string; name: string; contentDigest: string }) => void;
+		ondisabled: (name: string) => void;
+	} = $props();
+
+	type FileNode = { path: string; content: string };
+
+	let files = $state<FileNode[]>([]);
+	let selectedPath = $state<string | null>(null);
+	let version = $state(skill.version);
+	let description = $state(skill.description ?? '');
+	let loading = $state(false);
+	let saving = $state(false);
+	let dirty = $state(false);
+	let newFilePath = $state('');
+	let showNewFile = $state(false);
+
+	const selectedFile = $derived(files.find((f) => f.path === selectedPath) ?? null);
+	const hasManifest = $derived(files.some((f) => f.path === 'SKILL.md'));
+	const sortedFiles = $derived([...files].sort((a, b) => a.path.localeCompare(b.path)));
+
+	async function loadFiles() {
+		loading = true;
+		try {
+			const res = await api.agentSkillFiles(slug, skill.name);
+			files = res.files.map((f) => ({ path: f.path, content: f.content }));
+			if (files.length > 0 && selectedPath === null) {
+				selectedPath = files[0]!.path;
+			}
+			dirty = false;
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			loading = false;
+		}
+	}
+
+	function selectFile(path: string) {
+		selectedPath = path;
+	}
+
+	function updateContent(path: string, content: string) {
+		const file = files.find((f) => f.path === path);
+		if (file) {
+			file.content = content;
+			dirty = true;
+			if (path === 'SKILL.md') {
+				const desc = parseDescription(content);
+				if (desc !== null) description = desc;
+			}
+		}
+	}
+
+	function addFile() {
+		const path = newFilePath.trim();
+		if (path === '') {
+			toastError('文件路径不能为空');
+			return;
+		}
+		if (files.some((f) => f.path === path)) {
+			toastError(`文件已存在：${path}`);
+			return;
+		}
+		if (path.startsWith('/') || path.includes('..')) {
+			toastError('文件路径必须为相对路径');
+			return;
+		}
+		files.push({ path, content: '' });
+		selectedPath = path;
+		newFilePath = '';
+		showNewFile = false;
+		dirty = true;
+	}
+
+	function deleteFile(path: string) {
+		if (path === 'SKILL.md') {
+			toastError('SKILL.md 是必需的 manifest，不能删除');
+			return;
+		}
+		files = files.filter((f) => f.path !== path);
+		if (selectedPath === path) {
+			selectedPath = files.length > 0 ? files[0]!.path : null;
+		}
+		dirty = true;
+	}
+
+	function parseDescription(manifest: string): string | null {
+		const match = /^description:\s*['"]?([^'"\r\n]+)['"]?\s*$/m.exec(manifest);
+		return match ? match[1]!.trim() : null;
+	}
+
+	async function save() {
+		if (!hasManifest) {
+			toastError('缺少 SKILL.md manifest 文件');
+			return;
+		}
+		const trimmedVersion = version.trim();
+		if (trimmedVersion === '') {
+			toastError('版本号不能为空');
+			return;
+		}
+		saving = true;
+		try {
+			const fileEntries: SkillFileEntry[] = files.map((f) => ({ path: f.path, content: f.content }));
+			const result = await api.installAgentSkill(slug, skill.name, {
+				version: trimmedVersion,
+				files: fileEntries,
+			});
+			dirty = false;
+			toastSuccess('技能已保存');
+			oninstalled(result);
+			await loadFiles();
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			saving = false;
+		}
+	}
+
+	async function disable() {
+		saving = true;
+		try {
+			await api.patchAgentSkill(slug, skill.name, { disabled: true });
+			toastSuccess('技能已禁用');
+			ondisabled(skill.name);
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			saving = false;
+		}
+	}
+
+	function saveDescription() {
+		const manifest = files.find((f) => f.path === 'SKILL.md');
+		if (!manifest) return;
+		const updated = updateFrontmatter(manifest.content, 'description', description.trim());
+		manifest.content = updated;
+		dirty = true;
+	}
+
+	function updateFrontmatter(content: string, key: string, value: string): string {
+		const regex = new RegExp(`^(${key}:\\s*)(.*?)(\\s*)$`, 'm');
+		if (regex.test(content)) {
+			return content.replace(regex, `${key}: ${value}`);
+		}
+		const lines = content.split('\n');
+		if (lines[0] === '---') {
+			lines.splice(1, 0, `${key}: ${value}`);
+		} else {
+			lines.unshift('---', `${key}: ${value}`, '---');
+		}
+		return lines.join('\n');
+	}
+
+	$effect(() => {
+		if (skill.name) loadFiles();
+	});
+</script>
+
+<div class="saas-card-pad">
+	<div class="mb-4 flex flex-wrap items-center gap-2">
+		<span class="saas-badge-primary font-mono">{skill.name}</span>
+		<span class="text-sm text-surface-700">v{skill.version}</span>
+		{#if skill.disabledAt}
+			<span class="saas-badge-error">已禁用</span>
+		{/if}
+	</div>
+
+	<div class="mb-4 grid grid-cols-1 gap-4 md:grid-cols-2">
+		<div>
+			<label for="skill-version-{skill.id}" class="saas-label">版本号</label>
+			<input id="skill-version-{skill.id}" class="saas-input" bind:value={version} placeholder="如 0.1.0" />
+		</div>
+		<div>
+			<label for="skill-desc-{skill.id}" class="saas-label">描述（同步到 SKILL.md frontmatter）</label>
+			<div class="flex gap-2">
+				<input id="skill-desc-{skill.id}" class="saas-input" bind:value={description} onchange={saveDescription} />
+			</div>
+		</div>
+	</div>
+
+	<div class="mb-4 flex flex-wrap items-center gap-2 text-xs text-surface-600">
+		<span>digest: <code class="font-mono">{skill.contentDigest.slice(0, 12)}</code></span>
+		<span>·</span>
+		<span>更新于 {fmtDate(skill.updatedAt)}</span>
+		{#if skill.boundRoleIds.length > 0}
+			<span>·</span>
+			<span>绑定角色: {skill.boundRoleIds.join(', ')}</span>
+		{/if}
+		{#if dirty}
+			<span>·</span>
+			<span class="font-medium text-warning-700">未保存</span>
+		{/if}
+	</div>
+
+	{#if loading}
+		<div class="py-8 text-center text-sm text-surface-600">加载文件中…</div>
+	{:else}
+		<div class="grid grid-cols-1 gap-4 md:grid-cols-[16rem_1fr]">
+			<div class="border border-surface-300 bg-surface-100">
+				<div class="flex items-center justify-between border-b border-surface-300 px-3 py-2">
+					<span class="text-xs font-medium text-surface-700">文件</span>
+					<button
+						type="button"
+						class="text-xs text-primary-700 hover:text-primary-900"
+						onclick={() => (showNewFile = !showNewFile)}
+					>
+						{showNewFile ? '取消' : '+ 新增'}
+					</button>
+				</div>
+				{#if showNewFile}
+					<div class="border-b border-surface-300 px-3 py-2">
+						<input
+							class="saas-input text-xs"
+							placeholder="如 reference.md"
+							bind:value={newFilePath}
+							onkeydown={(e) => {
+								if (e.key === 'Enter') addFile();
+							}}
+						/>
+					</div>
+				{/if}
+				<div class="max-h-80 overflow-y-auto">
+					{#each sortedFiles as f (f.path)}
+						<button
+							type="button"
+							class="flex w-full items-center gap-2 px-3 py-1.5 text-left text-sm transition hover:bg-surface-200
+								{selectedPath === f.path ? 'bg-primary-100 text-primary-900' : 'text-surface-800'}"
+							onclick={() => selectFile(f.path)}
+						>
+							<Icon name="file" class="h-3.5 w-3.5 shrink-0 opacity-60" />
+							<span class="truncate font-mono text-xs">{f.path}</span>
+							{#if f.path === 'SKILL.md'}
+								<span class="ml-auto text-[10px] text-primary-700">manifest</span>
+							{:else}
+								<span
+									class="ml-auto text-xs text-surface-500 hover:text-error-700"
+									role="button"
+									tabindex="0"
+									onclick={(e) => {
+										e.stopPropagation();
+										deleteFile(f.path);
+									}}
+									onkeydown={(e) => {
+										if (e.key === 'Enter' || e.key === ' ') {
+											e.stopPropagation();
+											deleteFile(f.path);
+										}
+									}}
+								>
+									×
+								</span>
+							{/if}
+						</button>
+					{/each}
+					{#if files.length === 0}
+						<div class="px-3 py-4 text-center text-xs text-surface-600">暂无文件</div>
+					{/if}
+				</div>
+			</div>
+
+			<div>
+				{#if selectedFile}
+					<div class="mb-2 flex items-center gap-2">
+						<span class="font-mono text-xs text-surface-600">{selectedFile.path}</span>
+					</div>
+					<textarea
+						class="h-80 w-full resize-y border border-surface-300 bg-white p-3 font-mono text-xs text-surface-900 focus:border-primary-500 focus:outline-none"
+						bind:value={selectedFile.content}
+						oninput={() => (dirty = true)}
+					></textarea>
+				{:else}
+					<div class="flex h-80 items-center justify-center border border-surface-300 bg-surface-100 text-sm text-surface-600">
+						选择一个文件或新建文件
+					</div>
+				{/if}
+			</div>
+		</div>
+
+		<div class="mt-4 flex flex-wrap items-center gap-3 border-t border-surface-100 pt-4">
+			<button class="saas-btn-primary" onclick={save} disabled={saving || !dirty}>
+				{saving ? '保存中…' : '保存'}
+			</button>
+			{#if !skill.disabledAt}
+				<button class="saas-btn-danger" onclick={disable} disabled={saving}>
+					禁用
+				</button>
+			{/if}
+		</div>
+	{/if}
+</div>

hub/admin-web/src/lib/constants.ts

@@ -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: '飞书' },

hub/admin-web/src/lib/session.ts

@@ -32,9 +32,37 @@ 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.
+ */
+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();
+
+	// Alpha Silo public host: <slug>.educraft.paradigm-edu.net (or educraft-dev)
+	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];
+	return null;
+}
+
 export function redirectToLogin(): void {
-	const ret = encodeURIComponent(window.location.pathname + window.location.hash);
-	window.location.href = `/auth/feishu?returnTo=${ret}`;
+	if (window.location.pathname === '/admin/login') return;
+	const ret = encodeURIComponent(
+		window.location.pathname + window.location.search + window.location.hash,
+	);
+	const slug = resolveLoginOrgSlug();
+	if (slug === null) {
+		// Need an org slug for scoped OAuth — backend login helper can prompt.
+		window.location.href = `/admin/login?returnTo=${ret}`;
+		return;
+	}
+	window.location.href = `/auth/feishu/${encodeURIComponent(slug)}?returnTo=${ret}`;
 }
 
 export async function logout(): Promise<void> {

hub/admin-web/src/routes/+layout.svelte

@@ -25,6 +25,8 @@
 		{ key: 'projects', label: '项目', icon: 'projects' as const },
 		{ key: 'capacity', label: '容量', icon: 'overview' as const },
 		{ key: 'provider', label: '供应方', icon: 'provider' as const },
+		{ key: 'skills', label: '技能', icon: 'roles' as const },
+		{ key: 'roles', label: '角色', icon: 'roles' as const },
 		{ key: 'feishu', label: '飞书', icon: 'feishu' as const },
 	];
 
@@ -310,11 +312,7 @@
 	<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={`/admin/org/${org.slug}/projects`} class="saas-btn-ghost px-2!" aria-label="返回项目列表">
 					<Icon name="menu" class="h-5 w-5" />
 				</a>
 				<div class="min-w-0">

hub/admin-web/src/routes/admin/org/[slug]/projects/+page.svelte

@@ -14,9 +14,7 @@
 	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(($session.me?.organizations.find((o) => o.slug === slug) as OrgMembership | undefined) ?? null);
 	const isAdmin = $derived(!!org && (org.role === 'OWNER' || org.role === 'ADMIN'));
 
 	let data = $state<ExplorerData | null>(null);
@@ -32,6 +30,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;
@@ -113,8 +123,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 +132,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>
 

hub/admin-web/src/routes/admin/org/[slug]/projects/[projectId]/+page.svelte

@@ -15,6 +15,7 @@
 	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
 	import EmptyState from '$lib/components/EmptyState.svelte';
 	import SelectField from '$lib/components/SelectField.svelte';
+	import Icon from '$lib/components/Icon.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';
 
 	const slug = $derived(page.params.slug ?? '');
@@ -158,7 +159,8 @@
 			href={`/admin/org/${slug}/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" />
+			返回项目列表
 		</a>
 	</div>
 

hub/admin-web/src/routes/admin/org/[slug]/roles/+page.svelte

@@ -0,0 +1,129 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type AgentRoleRow, type AgentModelRow, type AgentSkillRow } from '$lib/api';
+	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 RoleCard from '$lib/components/RoleCard.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	const slug = $derived(page.params.slug ?? '');
+
+	let roles = $state<AgentRoleRow[]>([]);
+	let models = $state<AgentModelRow[]>([]);
+	let skills = $state<AgentSkillRow[]>([]);
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+
+	let newRoleId = $state('');
+	let newLabel = $state('');
+	let adding = $state(false);
+
+	async function load() {
+		loading = true;
+		error = null;
+		try {
+			const [r, s] = await Promise.all([api.agentRoles(slug), api.agentSkills(slug)]);
+			roles = r.roles;
+			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 {
+			loading = false;
+		}
+	}
+
+	async function add() {
+		const roleId = newRoleId.trim();
+		const label = newLabel.trim();
+		if (roleId === '' || label === '') {
+			toastError('角色 ID 与显示名均为必填');
+			return;
+		}
+		if (roles.some((r) => r.roleId === roleId)) {
+			toastError(`角色 ID 已存在：${roleId}`);
+			return;
+		}
+		adding = true;
+		try {
+			const created = await api.upsertAgentRole(slug, roleId, { label });
+			roles = [...roles, created];
+			newRoleId = '';
+			newLabel = '';
+			toastSuccess('角色已创建');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			adding = false;
+		}
+	}
+
+	function onRoleUpdated(updated: AgentRoleRow) {
+		roles = roles.map((x) => (x.roleId === updated.roleId ? { ...updated, skillNames: x.skillNames } : x));
+		if (updated.isDefault) {
+			roles = roles.map((x) => (x.roleId === updated.roleId ? x : { ...x, isDefault: false }));
+		}
+	}
+
+	function onRoleSkillsChanged(roleId: string, skillNames: string[]) {
+		roles = roles.map((x) => (x.roleId === roleId ? { ...x, skillNames } : x));
+	}
+
+	$effect(() => {
+		if (slug) load();
+	});
+</script>
+
+<PageHeader
+	title="角色"
+	description="角色是组织级数据：组合默认模型、系统提示词、工具白名单与已绑定技能。角色 ID 即飞书斜杠命令（如 /draft）。"
+/>
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else}
+	<div class="saas-card-pad mb-6">
+		<h2 class="saas-section-title mb-4">新建角色</h2>
+		<div class="grid gap-3 sm:grid-cols-[10rem_1fr_auto]">
+			<input
+				class="saas-input font-mono text-sm"
+				placeholder="角色 ID（如 draft）"
+				bind:value={newRoleId}
+				onkeydown={(e) => {
+					if (e.key === 'Enter') add();
+				}}
+			/>
+			<input
+				class="saas-input"
+				placeholder="显示名（如 草稿）"
+				bind:value={newLabel}
+				onkeydown={(e) => {
+					if (e.key === 'Enter') add();
+				}}
+			/>
+			<button class="saas-btn-primary" onclick={add} disabled={adding}>新建</button>
+		</div>
+		<p class="mt-2 text-xs text-surface-600">角色 ID 仅允许小写字母、数字、下划线与连字符，且以字母或数字开头。</p>
+	</div>
+
+	{#if roles.length === 0}
+		<div class="saas-card">
+			<EmptyState title="暂无角色" description="组织必须且只能有一个启用中的默认角色；新建第一个角色将自动成为默认。" />
+		</div>
+	{:else}
+		<div class="space-y-4">
+			{#each roles as r (r.roleId)}
+				<RoleCard {r} {models} {skills} {slug} onupdated={onRoleUpdated} onskillschanged={onRoleSkillsChanged} />
+			{/each}
+		</div>
+	{/if}
+{/if}

hub/admin-web/src/routes/admin/org/[slug]/skills/+page.svelte

@@ -0,0 +1,141 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type AgentSkillRow, type SkillFileEntry } from '$lib/api';
+	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 SkillEditor from '$lib/components/SkillEditor.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	const slug = $derived(page.params.slug ?? '');
+
+	let skills = $state<AgentSkillRow[]>([]);
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+
+	let showNewSkill = $state(false);
+	let newSkillName = $state('');
+	let newSkillVersion = $state('0.1.0');
+	let newSkillDescription = $state('');
+	let creating = $state(false);
+
+	async function load() {
+		loading = true;
+		error = null;
+		try {
+			const res = await api.agentSkills(slug);
+			skills = res.skills;
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	async function createSkill() {
+		const name = newSkillName.trim();
+		if (name === '') {
+			toastError('技能名称不能为空');
+			return;
+		}
+		if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(name)) {
+			toastError('技能名称仅允许小写字母、数字和连字符，且以字母或数字开头');
+			return;
+		}
+		const version = newSkillVersion.trim();
+		if (version === '') {
+			toastError('版本号不能为空');
+			return;
+		}
+		creating = true;
+		try {
+			const manifest = buildManifest(name, newSkillDescription.trim());
+			const files: SkillFileEntry[] = [{ path: 'SKILL.md', content: manifest }];
+			const result = await api.installAgentSkill(slug, name, { version, files });
+			toastSuccess(`技能 ${result.name} 已创建`);
+			newSkillName = '';
+			newSkillDescription = '';
+			showNewSkill = false;
+			await load();
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			creating = false;
+		}
+	}
+
+	function buildManifest(name: string, description: string): string {
+		const desc = description === '' ? name : description;
+		return `---\nname: ${name}\ndescription: ${desc}\n---\n# ${name}\n\n`;
+	}
+
+	function onInstalled(_result: { id: string; name: string; contentDigest: string }) {
+		load();
+	}
+
+	function onDisabled(_name: string) {
+		load();
+	}
+
+	$effect(() => {
+		if (slug) load();
+	});
+</script>
+
+<PageHeader
+	title="技能"
+	description="技能是组织级 Agent 能力包：一个包含 SKILL.md manifest 的目录。技能内容按 SHA-256 content-addressed 存储，变更后绑定角色的活跃会话自动归档。"
+/>
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else}
+	<div class="saas-card-pad mb-6">
+		<div class="flex items-center justify-between">
+			<h2 class="saas-section-title">新建技能</h2>
+			<button class="text-sm text-primary-700 hover:text-primary-900" onclick={() => (showNewSkill = !showNewSkill)}>
+				{showNewSkill ? '取消' : '+ 新建'}
+			</button>
+		</div>
+		{#if showNewSkill}
+			<div class="mt-4 grid gap-3 sm:grid-cols-[12rem_8rem_1fr_auto]">
+				<input
+					class="saas-input font-mono text-sm"
+					placeholder="技能名（如 typst-help）"
+					bind:value={newSkillName}
+				/>
+				<input
+					class="saas-input text-sm"
+					placeholder="版本号"
+					bind:value={newSkillVersion}
+				/>
+				<input
+					class="saas-input text-sm"
+					placeholder="描述"
+					bind:value={newSkillDescription}
+				/>
+				<button class="saas-btn-primary" onclick={createSkill} disabled={creating}>
+					{creating ? '创建中…' : '创建'}
+				</button>
+			</div>
+			<p class="mt-2 text-xs text-surface-600">
+				技能名称仅允许小写字母、数字和连字符，且以字母或数字开头。创建后会生成 SKILL.md 模板。
+			</p>
+		{/if}
+	</div>
+
+	{#if skills.length === 0}
+		<div class="saas-card">
+			<EmptyState title="暂无技能" description="新建一个技能，然后在角色管理中绑定到角色。" />
+		</div>
+	{:else}
+		<div class="space-y-4">
+			{#each skills as skill (skill.id)}
+				<SkillEditor {slug} {skill} oninstalled={onInstalled} ondisabled={onDisabled} />
+			{/each}
+		</div>
+	{/if}
+{/if}

hub/admin-web/vite.config.ts

@@ -8,6 +8,10 @@ export default defineConfig({
 		proxy: {
 			'/api': 'http://127.0.0.1:8788',
 			'/auth': 'http://127.0.0.1:8788',
+			// Backend owns /admin/login (registered before the SPA fallback in
+			// src/admin/static.ts). Proxy it in dev so the SPA doesn't re-render
+			// its layout on that path and 401-redirect into a returnTo loop.
+			'/admin/login': 'http://127.0.0.1:8788',
 		},
 	},
 });

hub/deploy/deploy_fleet_release.sh

@@ -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

hub/deploy/deploy_platform.sh

@@ -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.

hub/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@paradigm/hub",
-  "version": "0.0.26",
+  "version": "0.0.31",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@paradigm/hub",
-      "version": "0.0.26",
+      "version": "0.0.31",
       "dependencies": {
         "@anthropic-ai/claude-agent-sdk": "^0.3.202",
         "@fastify/cookie": "^11.0.2",

hub/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paradigm/hub",
-  "version": "0.0.26",
+  "version": "0.0.31",
   "private": true,
   "type": "module",
   "engines": {

hub/prisma/migrations/20260718120000_usage_fact_ledger/migration.sql

@@ -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;

hub/prisma/schema.prisma

@@ -596,9 +596,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 +616,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 +822,50 @@ 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])
+}

hub/scripts/dev-bootstrap.ts

@@ -0,0 +1,52 @@
+import { config } from "dotenv";
+config();
+
+import { PrismaClient } from "@prisma/client";
+import { bootstrapAlphaSilo } from "../src/deployment/bootstrap-silo.js";
+import { loadLocalSecretKeyring, LocalSecretEnvelope } from "../src/security/secretEnvelope.js";
+
+async function main(): Promise<void> {
+  const keyringFile = process.env["HUB_SECRET_KEYRING_FILE"];
+  if (!keyringFile) throw new Error("HUB_SECRET_KEYRING_FILE is required");
+  const secrets = new LocalSecretEnvelope(await loadLocalSecretKeyring());
+  const prisma = new PrismaClient();
+  try {
+    const result = await bootstrapAlphaSilo(
+      prisma,
+      secrets,
+      {
+        organization: {
+          id: "org_default",
+          slug: "default",
+          name: "Default Organization",
+        },
+        owner: {
+          openId: process.env["FEISHU_BOT_OPEN_ID"] ?? "dev-owner",
+          displayName: "Dev Owner",
+        },
+        feishu: {
+          appId: process.env["FEISHU_APP_ID"] ?? "dev-app",
+          appSecret: process.env["FEISHU_APP_SECRET"] ?? "dev-secret",
+          botOpenId: process.env["FEISHU_BOT_OPEN_ID"] ?? "dev-bot",
+        },
+        provider: {
+          providerId: "openrouter",
+          baseUrl: process.env["ANTHROPIC_BASE_URL"] ?? "https://openrouter.ai/api",
+          authToken: process.env["ANTHROPIC_AUTH_TOKEN"] ?? "dev-token",
+        },
+      },
+      {
+        feishu: async () => undefined,
+        provider: async () => undefined,
+      },
+    );
+    console.log("bootstrap ok:", JSON.stringify(result, null, 2));
+  } finally {
+    await prisma.$disconnect();
+  }
+}
+
+main().catch((error: unknown) => {
+  console.error("[dev-bootstrap] failed:", error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

hub/src/admin/routes/agentConfigRoutes.ts

@@ -0,0 +1,246 @@
+/**
+ * Org-admin Agent configuration routes (ADR-0017 / ADR-0018).
+ *
+ * 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
+ * content-addressed persistent store used by the host-console CLI. All skill
+ * content flows through `importSkillFromFiles` → `inspectSkillDirectory` →
+ * `commitSkillContent`, so the web path and CLI path share one ingestion
+ * pipeline and one set of safety checks (SKILL.md manifest required, 512-file
+ * / 16-byte limits, symlink rejection).
+ */
+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";
+
+export interface AgentConfigRouteConfig {
+  readonly prisma: PrismaClient;
+  readonly sessionSecret: string;
+  readonly skillStoreRoot: string;
+  readonly secretEnvelope: LocalSecretEnvelope;
+}
+
+export async function registerAgentConfigRoutes(
+  app: FastifyInstance,
+  config: AgentConfigRouteConfig,
+): 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 {
+      const { orgSlug } = request.params as { orgSlug: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      const roles = await agentConfig.listRoles({ organizationId: auth.organization.id });
+      return { roles };
+    } catch (err) {
+      return handleRouteError(reply, err);
+    }
+  });
+
+  app.put("/api/org/:orgSlug/agent-roles/:roleId", async (request, reply) => {
+    try {
+      const { orgSlug, roleId } = request.params as { orgSlug: string; roleId: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      const body = request.body as {
+        label?: unknown;
+        defaultModel?: unknown;
+        systemPrompt?: unknown;
+        tools?: unknown;
+        sortOrder?: unknown;
+        isDefault?: unknown;
+      };
+      if (typeof body.label !== "string" || body.label.trim() === "") {
+        return reply.status(400).send({
+          error: { code: "bad_request", message: "label is required" },
+        });
+      }
+      const role = await agentConfig.upsertRole({
+        organizationId: auth.organization.id,
+        roleId,
+        label: body.label,
+        ...(body.defaultModel === null || typeof body.defaultModel === "string"
+          ? { defaultModel: body.defaultModel as string | null }
+          : {}),
+        ...(body.systemPrompt === null || typeof body.systemPrompt === "string"
+          ? { systemPrompt: body.systemPrompt as string | null }
+          : {}),
+        ...(body.tools === null || Array.isArray(body.tools)
+          ? { tools: body.tools as readonly string[] | null }
+          : {}),
+        ...(typeof body.sortOrder === "number" ? { sortOrder: body.sortOrder } : {}),
+        ...(typeof body.isDefault === "boolean" ? { isDefault: body.isDefault } : {}),
+      });
+      return role;
+    } catch (err) {
+      return handleRouteError(reply, err);
+    }
+  });
+
+  app.put("/api/org/:orgSlug/agent-roles/:roleId/skills", async (request, reply) => {
+    try {
+      const { orgSlug, roleId } = request.params as { orgSlug: string; roleId: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      const body = request.body as { skillNames?: unknown };
+      if (!Array.isArray(body.skillNames) || body.skillNames.some((n) => typeof n !== "string")) {
+        return reply.status(400).send({
+          error: { code: "bad_request", message: "skillNames must be a string array" },
+        });
+      }
+      await agentConfig.setRoleSkills({
+        organizationId: auth.organization.id,
+        roleId,
+        skillNames: body.skillNames as readonly string[],
+      });
+      return { skillNames: body.skillNames as string[] };
+    } catch (err) {
+      return handleRouteError(reply, err);
+    }
+  });
+
+  app.get("/api/org/:orgSlug/agent-skills", async (request, reply) => {
+    try {
+      const { orgSlug } = request.params as { orgSlug: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      const skills = await agentConfig.listSkills({ organizationId: auth.organization.id });
+      return { skills };
+    } catch (err) {
+      return handleRouteError(reply, err);
+    }
+  });
+
+  app.get("/api/org/:orgSlug/agent-skills/:name/files", async (request, reply) => {
+    try {
+      const { orgSlug, name } = request.params as { orgSlug: string; name: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      const skills = await agentConfig.listSkills({ organizationId: auth.organization.id });
+      const skill = skills.find((s) => s.name === name && s.disabledAt === null);
+      if (skill === undefined) {
+        return reply.status(404).send({
+          error: { code: "not_found", message: `skill not found: ${name}` },
+        });
+      }
+      const files = await agentConfig.readSkillFiles({
+        organizationId: auth.organization.id,
+        contentDigest: skill.contentDigest,
+      });
+      return { files };
+    } catch (err) {
+      return handleRouteError(reply, err);
+    }
+  });
+
+  app.put("/api/org/:orgSlug/agent-skills/:name", async (request, reply) => {
+    try {
+      const { orgSlug, name } = request.params as { orgSlug: string; name: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      const body = request.body as { version?: unknown; files?: unknown };
+      if (typeof body.version !== "string" || body.version.trim() === "") {
+        return reply.status(400).send({
+          error: { code: "bad_request", message: "version is required" },
+        });
+      }
+      if (!Array.isArray(body.files) || body.files.length === 0) {
+        return reply.status(400).send({
+          error: { code: "bad_request", message: "files must be a non-empty array" },
+        });
+      }
+      const skillFiles: Array<{ readonly path: string; readonly bytes: Buffer }> = [];
+      for (const entry of body.files) {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+          return reply.status(400).send({
+            error: { code: "bad_request", message: "each file must be an object" },
+          });
+        }
+        const e = entry as { path?: unknown; content?: unknown };
+        if (typeof e.path !== "string" || typeof e.content !== "string") {
+          return reply.status(400).send({
+            error: { code: "bad_request", message: "each file needs string path and content" },
+          });
+        }
+        skillFiles.push({ path: e.path, bytes: Buffer.from(e.content, "utf8") });
+      }
+      const result = await agentConfig.installSkillFromFiles({
+        organizationId: auth.organization.id,
+        files: skillFiles,
+        version: body.version,
+      });
+      // The manifest name is authoritative — reject if it doesn't match the
+      // URL param, so clients can't silently rename a skill under a different
+      // route key.
+      if (result.name !== name) {
+        return reply.status(400).send({
+          error: {
+            code: "bad_request",
+            message: `skill manifest name "${result.name}" does not match route "${name}"`,
+          },
+        });
+      }
+      return { id: result.id, name: result.name, contentDigest: result.contentDigest };
+    } catch (err) {
+      return handleRouteError(reply, err);
+    }
+  });
+
+  app.patch("/api/org/:orgSlug/agent-skills/:name", async (request, reply) => {
+    try {
+      const { orgSlug, name } = request.params as { orgSlug: string; name: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      const body = request.body as { description?: unknown; disabled?: unknown };
+      if (body.disabled === true) {
+        await agentConfig.disableSkill({ organizationId: auth.organization.id, name });
+        return { disabled: true };
+      }
+      if (typeof body.description === "string") {
+        await agentConfig.updateSkillDescription({
+          organizationId: auth.organization.id,
+          name,
+          description: body.description,
+        });
+        return { updated: true };
+      }
+      return reply.status(400).send({
+        error: { code: "bad_request", message: "provide description or disabled: true" },
+      });
+    } catch (err) {
+      return handleRouteError(reply, err);
+    }
+  });
+
+  app.get("/api/org/:orgSlug/agent-models", async (request, reply) => {
+    try {
+      const { orgSlug } = request.params as { orgSlug: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      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);
+    }
+  });
+}

hub/src/admin/routes/authRoutes.ts

@@ -433,8 +433,10 @@ async function resolvePostLoginRedirect(
     });
     if (intended === null) return "/admin?error=not_an_active_org_member";
     const orgRoot = `/admin/org/${intended.organization.slug}`;
+    // 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 `/auth/feishu/complete?org=${encodeURIComponent(intended.organization.name)}`;
+      return orgRoot;
     }
     return returnTo === orgRoot || returnTo.startsWith(`${orgRoot}/`) ? returnTo : orgRoot;
   }

hub/src/admin/routes/explorerRoutes.ts

@@ -155,7 +155,7 @@ export async function registerExplorerRoutes(
         workspaceRoot: config.projectWorkspaceRoot,
         ...(typeof body.folderId === "string" ? { folderId: body.folderId } : {}),
       });
-      return reply.status(201).send(result);
+      return reply.status(201).send({ id: result.projectId, name: body.name });
     } catch (err) {
       return handleRouteError(reply, err);
     }

hub/src/admin/routes/orgRoutes.ts

@@ -16,6 +16,8 @@ import { registerSessionsAndUsageRoutes } from "./sessionsRoutes.js";
 import { registerTeamsRoutes } from "./teamsRoutes.js";
 import { registerProviderConnectionRoutes } from "./providerConnectionRoutes.js";
 import { registerCapacityRoutes } from "./capacityRoutes.js";
+import { readSkillStoreRoot } from "../../agent/skillStore.js";
+import { registerAgentConfigRoutes } from "./agentConfigRoutes.js";
 import type { LocalSecretEnvelope } from "../../security/secretEnvelope.js";
 import type { ProviderReadinessProbe } from "../../connections/providerReadiness.js";
 import type { FeishuReadinessProbe } from "../../connections/feishuReadiness.js";
@@ -110,6 +112,12 @@ export async function registerOrgRoutes(app: FastifyInstance, config: OrgRouteCo
     prisma: config.prisma,
     sessionSecret: config.sessionSecret,
   });
+  await registerAgentConfigRoutes(app, {
+    prisma: config.prisma,
+    sessionSecret: config.sessionSecret,
+    skillStoreRoot: readSkillStoreRoot(),
+    secretEnvelope: config.secretEnvelope,
+  });
   await registerSessionsAndUsageRoutes(app, {
     prisma: config.prisma,
     sessionSecret: config.sessionSecret,

hub/src/agent/configuration.ts

@@ -1,10 +1,37 @@
 import type { PrismaClient } from "@prisma/client";
 import { Prisma } from "@prisma/client";
 import { assertSupportedRoleTools } from "./roleTools.js";
-import { importSkillDirectory } from "./skillStore.js";
+import { importSkillDirectory, importSkillFromFiles, readSkillFiles, type SkillFileInput, type SkillFileOutput } from "./skillStore.js";
 
 const ROLE_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 
+export interface AgentRoleRow {
+  readonly id: string;
+  readonly roleId: string;
+  readonly label: string;
+  readonly defaultModel: string | null;
+  readonly systemPrompt: string | null;
+  readonly tools: readonly string[] | null;
+  readonly sortOrder: number;
+  readonly isDefault: boolean;
+  readonly disabledAt: string | null;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly skillNames: readonly string[];
+}
+
+export interface AgentSkillRow {
+  readonly id: string;
+  readonly name: string;
+  readonly version: string;
+  readonly description: string | null;
+  readonly contentDigest: string;
+  readonly disabledAt: string | null;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly boundRoleIds: readonly string[];
+}
+
 /**
  * Deep module for controlled host-console Agent configuration. It owns the
  * filesystem/DB ordering, Organization checks and role-skill composition so
@@ -13,43 +40,227 @@ const ROLE_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 export class OrganizationAgentConfiguration {
   constructor(
     private readonly prisma: PrismaClient,
-    private readonly skillStoreRoot: string,
+    private readonly skillStoreRoot: string | null,
   ) {}
 
+  async listRoles(input: { readonly organizationId: string }): Promise<readonly AgentRoleRow[]> {
+    await this.requireActiveOrganization(input.organizationId);
+    const roles = await this.prisma.organizationAgentRole.findMany({
+      where: { organizationId: input.organizationId, disabledAt: null },
+      orderBy: [{ sortOrder: "asc" }, { roleId: "asc" }],
+      include: {
+        skillBindings: {
+          orderBy: [{ sortOrder: "asc" }, { agentSkillId: "asc" }],
+          select: { skill: { select: { name: true, disabledAt: true } } },
+        },
+      },
+    });
+    return roles.map((role) => toRoleRow(role));
+  }
+
+  async listSkills(input: { readonly organizationId: string }): Promise<readonly AgentSkillRow[]> {
+    await this.requireActiveOrganization(input.organizationId);
+    const skills = await this.prisma.organizationAgentSkill.findMany({
+      where: { organizationId: input.organizationId, disabledAt: null },
+      orderBy: [{ name: "asc" }],
+      include: {
+        roleBindings: {
+          where: { role: { disabledAt: null } },
+          select: { role: { select: { roleId: true } } },
+        },
+      },
+    });
+    return skills.map((skill) => ({
+      id: skill.id,
+      name: skill.name,
+      version: skill.version,
+      description: skill.description,
+      contentDigest: skill.contentDigest,
+      disabledAt: skill.disabledAt === null ? null : skill.disabledAt.toISOString(),
+      createdAt: skill.createdAt.toISOString(),
+      updatedAt: skill.updatedAt.toISOString(),
+      boundRoleIds: skill.roleBindings.map((binding) => binding.role.roleId),
+    }));
+  }
+
   async installSkill(input: {
     readonly organizationId: string;
     readonly sourceDir: string;
     readonly version: string;
   }): Promise<{ readonly id: string; readonly name: string; readonly contentDigest: string }> {
+    const storeRoot = this.requireSkillStoreRoot();
     await this.requireActiveOrganization(input.organizationId);
     const version = nonEmpty(input.version, "skill version");
     const imported = await importSkillDirectory({
       sourceDir: input.sourceDir,
-      storeRoot: this.skillStoreRoot,
+      storeRoot,
     });
+    return this.commitInstalledSkill({
+      organizationId: input.organizationId,
+      imported,
+      version,
+      action: "agent_skill.installed",
+    });
+  }
+
+  /**
+   * Install or replace a skill from an in-memory file list (web upload path).
+   * Same content-addressed storage, same session archival semantics as
+   * `installSkill`; only the ingestion source differs.
+   */
+  async installSkillFromFiles(input: {
+    readonly organizationId: string;
+    readonly files: readonly SkillFileInput[];
+    readonly version: string;
+  }): Promise<{ readonly id: string; readonly name: string; readonly contentDigest: string }> {
+    const storeRoot = this.requireSkillStoreRoot();
+    await this.requireActiveOrganization(input.organizationId);
+    const version = nonEmpty(input.version, "skill version");
+    const imported = await importSkillFromFiles({
+      files: input.files,
+      storeRoot,
+    });
+    return this.commitInstalledSkill({
+      organizationId: input.organizationId,
+      imported,
+      version,
+      action: "agent_skill.installed",
+    });
+  }
+
+  /**
+   * Read all files from the stored skill version identified by content digest.
+   * Returns UTF-8 content for each file; the web editor uses this to populate
+   * its file tree.
+   */
+  async readSkillFiles(input: {
+    readonly organizationId: string;
+    readonly contentDigest: string;
+  }): Promise<readonly SkillFileOutput[]> {
+    const storeRoot = this.requireSkillStoreRoot();
+    await this.requireActiveOrganization(input.organizationId);
+    const skill = await this.prisma.organizationAgentSkill.findFirst({
+      where: {
+        organizationId: input.organizationId,
+        contentDigest: input.contentDigest,
+      },
+      select: { id: true, disabledAt: true },
+    });
+    if (skill === null) {
+      throw new Error(`skill not found in organization for digest: ${input.contentDigest}`);
+    }
+    return readSkillFiles({
+      storeRoot,
+      contentDigest: input.contentDigest,
+    });
+  }
+
+  /**
+   * Disable a skill (soft-delete). Sets `disabledAt` and archives active
+   * sessions of every role bound to this skill, since the execution surface
+   * changes when a bound skill disappears.
+   */
+  async disableSkill(input: { readonly organizationId: string; readonly name: string }): Promise<void> {
+    await this.requireActiveOrganization(input.organizationId);
+    await this.prisma.$transaction(async (tx) => {
+      const skill = await tx.organizationAgentSkill.findUnique({
+        where: { organizationId_name: { organizationId: input.organizationId, name: input.name } },
+        select: { id: true, disabledAt: true, roleBindings: { select: { role: { select: { roleId: true } } } } },
+      });
+      if (skill === null) throw new Error(`active skill not found in organization: ${input.name}`);
+      if (skill.disabledAt !== null) return;
+      await tx.organizationAgentSkill.update({
+        where: { id: skill.id },
+        data: { disabledAt: new Date() },
+      });
+      await archiveRoleSessions(
+        tx,
+        input.organizationId,
+        skill.roleBindings.map((binding) => binding.role.roleId),
+      );
+      await tx.auditEntry.create({
+        data: {
+          organizationId: input.organizationId,
+          action: "agent_skill.disabled",
+          metadata: { name: input.name },
+        },
+      });
+    });
+  }
+
+  /**
+   * Update only the `description` label of a skill. This is a label change,
+   * not an execution-surface change — no session archival (ADR-0017).
+   */
+  async updateSkillDescription(input: {
+    readonly organizationId: string;
+    readonly name: string;
+    readonly description: string;
+  }): Promise<void> {
+    await this.requireActiveOrganization(input.organizationId);
+    const description = input.description.trim();
+    await this.prisma.$transaction(async (tx) => {
+      const skill = await tx.organizationAgentSkill.findUnique({
+        where: { organizationId_name: { organizationId: input.organizationId, name: input.name } },
+        select: { id: true, disabledAt: true },
+      });
+      if (skill === null || skill.disabledAt !== null) {
+        throw new Error(`active skill not found in organization: ${input.name}`);
+      }
+      await tx.organizationAgentSkill.update({
+        where: { id: skill.id },
+        data: { description: description === "" ? null : description },
+      });
+      await tx.auditEntry.create({
+        data: {
+          organizationId: input.organizationId,
+          action: "agent_skill.description_updated",
+          metadata: { name: input.name, description: description === "" ? null : description },
+        },
+      });
+    });
+  }
+
+  private requireSkillStoreRoot(): string {
+    if (this.skillStoreRoot === null) {
+      throw new Error("skill store root is not configured for this OrganizationAgentConfiguration");
+    }
+    return this.skillStoreRoot;
+  }
+
+  /**
+   * Shared DB commit for an imported skill: upsert the skill record, archive
+   * affected sessions if the content digest changed, and write an audit entry.
+   */
+  private async commitInstalledSkill(input: {
+    readonly organizationId: string;
+    readonly imported: { readonly name: string; readonly description: string | undefined; readonly contentDigest: string };
+    readonly version: string;
+    readonly action: string;
+  }): Promise<{ readonly id: string; readonly name: string; readonly contentDigest: string }> {
     return this.prisma.$transaction(async (tx) => {
       const previous = await tx.organizationAgentSkill.findUnique({
-        where: { organizationId_name: { organizationId: input.organizationId, name: imported.name } },
+        where: { organizationId_name: { organizationId: input.organizationId, name: input.imported.name } },
         select: { contentDigest: true },
       });
       const skill = await tx.organizationAgentSkill.upsert({
         where: {
           organizationId_name: {
             organizationId: input.organizationId,
-            name: imported.name,
+            name: input.imported.name,
           },
         },
         create: {
           organizationId: input.organizationId,
-          name: imported.name,
-          version,
-          description: imported.description ?? null,
-          contentDigest: imported.contentDigest,
+          name: input.imported.name,
+          version: input.version,
+          description: input.imported.description ?? null,
+          contentDigest: input.imported.contentDigest,
         },
         update: {
-          version,
-          description: imported.description ?? null,
-          contentDigest: imported.contentDigest,
+          version: input.version,
+          description: input.imported.description ?? null,
+          contentDigest: input.imported.contentDigest,
           disabledAt: null,
         },
         select: {
@@ -69,10 +280,10 @@ export class OrganizationAgentConfiguration {
       await tx.auditEntry.create({
         data: {
           organizationId: input.organizationId,
-          action: "agent_skill.installed",
+          action: input.action,
           metadata: {
             name: skill.name,
-            version,
+            version: input.version,
             contentDigest: skill.contentDigest,
           },
         },
@@ -90,7 +301,7 @@ export class OrganizationAgentConfiguration {
     readonly tools?: readonly string[] | null | undefined;
     readonly sortOrder?: number | undefined;
     readonly isDefault?: boolean | undefined;
-  }): Promise<{ readonly id: string; readonly roleId: string }> {
+  }): Promise<AgentRoleRow> {
     await this.requireActiveOrganization(input.organizationId);
     if (!ROLE_ID_PATTERN.test(input.roleId)) throw new Error(`invalid role id: ${input.roleId}`);
     const label = nonEmpty(input.label, "role label");
@@ -150,7 +361,12 @@ export class OrganizationAgentConfiguration {
           isDefault: effectiveIsDefault,
           disabledAt: null,
         },
-        select: { id: true, roleId: true },
+        include: {
+          skillBindings: {
+            orderBy: [{ sortOrder: "asc" }, { agentSkillId: "asc" }],
+            select: { skill: { select: { name: true, disabledAt: true } } },
+          },
+        },
       });
       const executionSurfaceChanged = previous !== null && (
         (input.defaultModel !== undefined && normalizeOptionalText(input.defaultModel) !== previous.defaultModel) ||
@@ -182,7 +398,7 @@ export class OrganizationAgentConfiguration {
           },
         },
       });
-      return role;
+      return toRoleRow(role);
     });
   }
 
@@ -295,3 +511,43 @@ function normalizeOptionalText(value: string | null | undefined): string | null
   const normalized = value.trim();
   return normalized === "" ? null : normalized;
 }
+
+function parseTools(value: Prisma.JsonValue): readonly string[] | null {
+  if (value === null) return null;
+  if (!Array.isArray(value)) return null;
+  return value.filter((t): t is string => typeof t === "string");
+}
+
+function toRoleRow(role: {
+  readonly id: string;
+  readonly roleId: string;
+  readonly label: string;
+  readonly defaultModel: string | null;
+  readonly systemPrompt: string | null;
+  readonly tools: Prisma.JsonValue;
+  readonly sortOrder: number;
+  readonly isDefault: boolean;
+  readonly disabledAt: Date | null;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+  readonly skillBindings: ReadonlyArray<{
+    readonly skill: { readonly name: string; readonly disabledAt: Date | null };
+  }>;
+}): AgentRoleRow {
+  return {
+    id: role.id,
+    roleId: role.roleId,
+    label: role.label,
+    defaultModel: role.defaultModel,
+    systemPrompt: role.systemPrompt,
+    tools: parseTools(role.tools),
+    sortOrder: role.sortOrder,
+    isDefault: role.isDefault,
+    disabledAt: role.disabledAt === null ? null : role.disabledAt.toISOString(),
+    createdAt: role.createdAt.toISOString(),
+    updatedAt: role.updatedAt.toISOString(),
+    skillNames: role.skillBindings
+      .filter((binding) => binding.skill.disabledAt === null)
+      .map((binding) => binding.skill.name),
+  };
+}

hub/src/agent/roleTools.ts

@@ -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 = [
@@ -26,11 +34,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>([

hub/src/agent/skillStore.ts

@@ -34,40 +34,134 @@ export async function importSkillDirectory(input: {
   readonly sourceDir: string;
   readonly storeRoot: string;
 }): Promise<ImportedSkillContent> {
-  const source = await inspectSkillDirectory(input.sourceDir);
+  return commitSkillContent({
+    storeRoot: input.storeRoot,
+    prepare: async (dir) => {
+      await cp(input.sourceDir, dir, { recursive: true, force: false, errorOnExist: true });
+      return inspectSkillDirectory(dir);
+    },
+  });
+}
+
+/**
+ * Import a skill from an in-memory file list (web upload path). Each file
+ * path is relative to the skill root and must be a simple relative path
+ * (no absolute, no `..`). A `SKILL.md` manifest is required.
+ */
+export async function importSkillFromFiles(input: {
+  readonly files: readonly SkillFileInput[];
+  readonly storeRoot: string;
+}): Promise<ImportedSkillContent> {
+  const seen = new Set<string>();
+  for (const file of input.files) {
+    validateSkillFilePath(file.path);
+    if (seen.has(file.path)) throw new Error(`duplicate skill file path: ${file.path}`);
+    seen.add(file.path);
+  }
+  return commitSkillContent({
+    storeRoot: input.storeRoot,
+    prepare: async (dir) => {
+      for (const file of input.files) {
+        const dest = join(dir, file.path);
+        const parent = join(dest, "..");
+        await mkdir(parent, { recursive: true, mode: 0o750 });
+        await writeFile(dest, file.bytes, { mode: 0o640 });
+      }
+      return inspectSkillDirectory(dir);
+    },
+  });
+}
+
+/**
+ * Read all files from a stored skill version (by content digest). Returns
+ * relative paths and UTF-8 decoded content for the web editor.
+ */
+export async function readSkillFiles(input: {
+  readonly storeRoot: string;
+  readonly contentDigest: string;
+}): Promise<readonly SkillFileOutput[]> {
+  if (!DIGEST_PATTERN.test(input.contentDigest)) {
+    throw new Error(`invalid content digest: ${input.contentDigest}`);
+  }
+  const dir = join(input.storeRoot, "versions", input.contentDigest);
+  const files: Array<{ readonly path: string; readonly bytes: Buffer }> = [];
+  await walk(resolve(dir), resolve(dir), files);
+  return files.sort((a, b) => a.path.localeCompare(b.path)).map((f) => ({
+    path: f.path,
+    content: f.bytes.toString("utf8"),
+  }));
+}
+
+export interface SkillFileInput {
+  readonly path: string;
+  readonly bytes: Buffer;
+}
+
+export interface SkillFileOutput {
+  readonly path: string;
+  readonly content: string;
+}
+
+/**
+ * Shared commit logic: populate a temp dir, inspect it, deduplicate against
+ * an existing `versions/<digest>/` destination, and atomically rename.
+ *
+ * `prepare(dir)` writes the skill content into `dir` and returns the inspected
+ * result (name, description, contentDigest). The caller owns the write;
+ * commitSkillContent owns the move.
+ */
+async function commitSkillContent(input: {
+  readonly storeRoot: string;
+  readonly prepare: (dir: string) => Promise<ImportedSkillContent>;
+}): Promise<ImportedSkillContent> {
   const versionsRoot = join(input.storeRoot, "versions");
   await mkdir(versionsRoot, { recursive: true, mode: 0o750 });
+  const temporary = join(versionsRoot, `.tmp-${randomUUID()}`);
+
+  let source: ImportedSkillContent;
+  try {
+    source = await input.prepare(temporary);
+  } catch (error) {
+    await rm(temporary, { recursive: true, force: true });
+    throw error;
+  }
+
   const destination = join(versionsRoot, source.contentDigest);
 
+  // If the destination already exists with identical content, reuse it.
   try {
     const existing = await inspectSkillDirectory(destination);
     if (existing.contentDigest !== source.contentDigest || existing.name !== source.name) {
       throw new Error(`stored skill content digest mismatch: ${source.name}`);
     }
+    await rm(temporary, { recursive: true, force: true });
     return source;
   } catch (error) {
     if (!isMissingPath(error)) throw error;
   }
 
-  const temporary = join(versionsRoot, `.tmp-${randomUUID()}`);
   try {
-    await cp(input.sourceDir, temporary, { recursive: true, force: false, errorOnExist: true });
-    const copied = await inspectSkillDirectory(temporary);
-    if (copied.contentDigest !== source.contentDigest || copied.name !== source.name) {
-      throw new Error(`skill changed while importing: ${source.name}`);
-    }
     await rename(temporary, destination);
   } catch (error) {
     await rm(temporary, { recursive: true, force: true });
     if (isDestinationExists(error)) {
       const existing = await inspectSkillDirectory(destination);
-      if (existing.contentDigest === source.contentDigest && existing.name === source.name) return source;
+      if (existing.contentDigest === source.contentDigest && existing.name === source.name) {
+        return source;
+      }
     }
     throw error;
   }
   return source;
 }
 
+function validateSkillFilePath(path: string): void {
+  if (path === "") throw new Error("skill file path is empty");
+  if (path.startsWith("/")) throw new Error(`skill file path must be relative: ${path}`);
+  if (path.includes("..")) throw new Error(`skill file path must not escape: ${path}`);
+  if (path.startsWith("\\")) throw new Error(`skill file path must be relative: ${path}`);
+}
+
 export async function prepareRunSkillPlugin(input: {
   readonly storeRoot: string;
   readonly runId: string;

hub/src/connections/providerModelCatalog.ts

@@ -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"),
+    }));
+  }
+}

hub/src/deployment/siloRateLimit.ts

@@ -1,3 +1,27 @@
+/**
+ * Silo-wide HTTP request rate limit (ADR-0022 `requestRate`).
+ *
+ * Counts dynamic traffic only: APIs, auth, and other application handlers.
+ * Static SPA assets and the org-admin HTML shell are exempt so a single page
+ * load (dozens of `/_app/*` chunks + favicon) does not exhaust the minute budget.
+ */
+
+/** Paths that must not consume the silo HTTP request-rate budget. */
+export function isSiloHttpRateLimitExempt(url: string): boolean {
+  const path = (url.split("?", 1)[0] ?? url) || "/";
+
+  if (path === "/api/healthz") return true;
+
+  // SvelteKit build output and top-level static files (see admin/static.ts).
+  if (path === "/_app" || path.startsWith("/_app/")) return true;
+  if (path === "/favicon.ico" || path === "/favicon.svg" || path === "/robots.txt") return true;
+
+  // SPA index shell for client-side routes (not an API).
+  if (path === "/admin" || path.startsWith("/admin/")) return true;
+
+  return false;
+}
+
 export class SiloFixedWindowRateLimiter {
   private windowStartedAt: number;
   private used = 0;

hub/src/feishu/card/builder.ts

@@ -42,6 +42,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 {

hub/src/feishu/fileDeliveryTool.ts

@@ -182,18 +182,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(

hub/src/feishu/slashCommands.ts

@@ -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;
+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,22 +154,35 @@ 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}`;
+    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: run.provider, model: run.model, runs: 0, inputTokens: 0, outputTokens: 0, costUsd: 0,
+        provider: f.provider, model, facts: 0, inputTokens: 0, outputTokens: 0, costUsd: 0,
       };
-    bucket.runs++;
-    bucket.inputTokens += run.inputTokens ?? 0;
-    bucket.outputTokens += run.outputTokens ?? 0;
+      bucket.facts += 1;
+      bucket.inputTokens += f.inputTokens ?? 0;
+      bucket.outputTokens += f.outputTokens ?? 0;
       bucket.costUsd += costUsd;
       buckets.set(key, bucket);
-    totalInputTokens += run.inputTokens ?? 0;
-    totalOutputTokens += run.outputTokens ?? 0;
+      totalInputTokens += f.inputTokens ?? 0;
+      totalOutputTokens += f.outputTokens ?? 0;
       totalCostUsd += costUsd;
     }
+  }
   const lines = [
     `${scope === "current" ? "当前角色会话" : "当前项目"}用量`,
     `已记录成本: ${formatInteger(recordedRuns)} runs · ${formatUsd(totalCostUsd)}`,
@@ -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");
 }

hub/src/feishu/trigger.ts

@@ -604,6 +604,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 +644,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, {

hub/src/hub.ts

@@ -14,7 +14,7 @@ import { verifyStoredFeishuApplicationEnvelopes } from "./connections/feishuAppl
 import { resolveActiveFeishuApplication } from "./connections/feishuApplicationConnections.js";
 import { readServerBinding } from "./settings/server.js";
 import { readSiloOrganizationId, requireSiloOrganization } from "./deployment/silo.js";
-import { SiloFixedWindowRateLimiter } from "./deployment/siloRateLimit.js";
+import { isSiloHttpRateLimitExempt, SiloFixedWindowRateLimiter } from "./deployment/siloRateLimit.js";
 
 function requireEnv(name: string): string {
   const value = process.env[name];
@@ -42,7 +42,9 @@ export async function startHub(): Promise<void> {
   const app = Fastify({ logger: true, bodyLimit: httpBodyLimit });
   const requestLimiter = new SiloFixedWindowRateLimiter(httpRequestsPerMinute, 60_000);
   app.addHook("onRequest", async (request, reply) => {
-    if (request.url === "/api/healthz") return;
+    // Static SPA assets / admin HTML shell / healthz do not count toward the
+    // silo requestRate budget (a full admin load can pull dozens of chunks).
+    if (isSiloHttpRateLimitExempt(request.url)) return;
     const decision = requestLimiter.consume();
     if (!decision.allowed) {
       await reply

hub/src/org/sessions.ts

@@ -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,
+      })),
     })),
   };
 }

hub/src/org/usage.ts

@@ -1,8 +1,14 @@
 /**
- * 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.
  */
 import type { Prisma, PrismaClient } from "@prisma/client";
 
@@ -32,6 +38,53 @@ export interface UsageReport {
   };
 }
 
+type FactRow = {
+  readonly inputTokens: number | null;
+  readonly outputTokens: number | null;
+  readonly costUsd: unknown;
+};
+
+type RunWithFacts = {
+  readonly projectId: string;
+  readonly usageFacts: readonly FactRow[];
+};
+
+/** A run is "recorded with cost" if any of its facts carries a known costUsd. */
+function runHasRecordedCost(facts: readonly FactRow[]): boolean {
+  return facts.some((f) => f.costUsd !== null && f.costUsd !== undefined);
+}
+
+/** Decimal→number for Prisma Decimal; null/undefined → null. */
+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;
+}
+
+interface RunRollup {
+  readonly hasCost: boolean;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly costUsd: number | null;
+}
+
+function rollupRun(facts: readonly FactRow[]): RunRollup {
+  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 = (costUsd ?? 0) + c;
+    }
+  }
+  return { hasCost, inputTokens, outputTokens, costUsd };
+}
+
 export async function getOrgUsage(
   prisma: PrismaClient,
   input: {
@@ -54,8 +107,9 @@ export async function getOrgUsage(
     return emptyReport(input.from, input.to);
   }
 
+  const projectIds = projects.map((p) => p.id);
   const runWhere: Prisma.AgentRunWhereInput = {
-    projectId: { in: projects.map((p) => p.id) },
+    projectId: { in: projectIds },
     ...(input.from !== undefined || input.to !== undefined
       ? {
           startedAt: {
@@ -66,20 +120,25 @@ export async function getOrgUsage(
       : {}),
   };
 
+  // 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,
     select: {
       projectId: true,
-      inputTokens: true,
-      outputTokens: true,
-      costUsd: true,
+      usageFacts: {
+        select: { inputTokens: true, outputTokens: true, costUsd: true },
+        orderBy: { occurredAt: "asc" },
+      },
     },
   });
 
   type MutableRow = {
-    projectId: string;
-    projectName: string;
-    folderId: string | null;
+    readonly projectId: string;
+    readonly projectName: string;
+    readonly folderId: string | null;
     runCount: number;
     runsWithCost: number;
     runsWithoutCost: number;
@@ -103,22 +162,33 @@ export async function getOrgUsage(
     });
   }
 
-  for (const run of runs) {
+  for (const run of runs as readonly RunWithFacts[]) {
     const row = byProject.get(run.projectId);
     if (row === undefined) continue;
+    const roll = rollupRun(run.usageFacts);
     row.runCount += 1;
-    row.inputTokens += run.inputTokens ?? 0;
-    row.outputTokens += run.outputTokens ?? 0;
-    if (run.costUsd === null) {
-      row.runsWithoutCost += 1;
-    } else {
+    if (roll.hasCost) {
       row.runsWithCost += 1;
-      const cost = Number(run.costUsd);
-      row.costUsd = (row.costUsd ?? 0) + cost;
+      row.costUsd = (row.costUsd ?? 0) + (roll.costUsd ?? 0);
+    } else {
+      row.runsWithoutCost += 1;
     }
+    row.inputTokens += roll.inputTokens;
+    row.outputTokens += roll.outputTokens;
   }
 
-  const projectsOut: ProjectUsageRow[] = [...byProject.values()];
+  const projectsOut: ProjectUsageRow[] = [...byProject.values()].map((r) => ({
+    projectId: r.projectId,
+    projectName: r.projectName,
+    folderId: r.folderId,
+    runCount: r.runCount,
+    runsWithCost: r.runsWithCost,
+    runsWithoutCost: r.runsWithoutCost,
+    inputTokens: r.inputTokens,
+    outputTokens: r.outputTokens,
+    costUsd: r.costUsd,
+  }));
+
   let runCount = 0;
   let runsWithCost = 0;
   let runsWithoutCost = 0;

hub/src/settings/runtime.ts

@@ -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,

hub/test/integration/admin-auth.test.ts

@@ -346,14 +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(
-        "/auth/feishu/complete?org=Test%20Default%20Organization",
-      );
-      const complete = await app.inject({ method: "GET", url: defaultCallback.headers.location! });
-      expect(complete.statusCode).toBe(200);
-      expect(complete.headers["content-type"]).toContain("text/html");
-      expect(complete.body).toContain("登录并加入组织成功");
-      expect(complete.body).toContain("Test Default Organization");
+      expect(defaultCallback.headers.location).toBe("/admin/org/test-default");
 
       await connections.disable({ organizationId: DEFAULT_ORG_ID, actorUserId: "scoped-owner" });
       const revoked = await app.inject({ method: "GET", url: "/api/me", headers: { cookie: sessionCookie } });

hub/test/integration/usage.test.ts

@@ -0,0 +1,191 @@
+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 ?? "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);
+  });
+
+  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);
+  });
+
+  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();
+  });
+});

hub/test/unit/feishu-reactions.test.ts

@@ -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 } }) => {

hub/test/unit/provider-model-catalog.test.ts

@@ -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");
+  });
+});

hub/test/unit/silo-rate-limit.test.ts

@@ -1,5 +1,8 @@
 import { describe, expect, it } from "vitest";
-import { SiloFixedWindowRateLimiter } from "../../src/deployment/siloRateLimit.js";
+import {
+  isSiloHttpRateLimitExempt,
+  SiloFixedWindowRateLimiter,
+} from "../../src/deployment/siloRateLimit.js";
 
 describe("Silo fixed-window rate limiter", () => {
   it("returns an explicit retry interval and resets at the next window", () => {
@@ -10,3 +13,24 @@ describe("Silo fixed-window rate limiter", () => {
     expect(limiter.consume(61_000)).toEqual({ allowed: true });
   });
 });
+
+describe("isSiloHttpRateLimitExempt", () => {
+  it("exempts healthz, SPA static assets, and the admin HTML shell", () => {
+    expect(isSiloHttpRateLimitExempt("/api/healthz")).toBe(true);
+    expect(isSiloHttpRateLimitExempt("/_app/version.json")).toBe(true);
+    expect(isSiloHttpRateLimitExempt("/_app/immutable/chunks/foo.js?v=1")).toBe(true);
+    expect(isSiloHttpRateLimitExempt("/favicon.ico")).toBe(true);
+    expect(isSiloHttpRateLimitExempt("/favicon.svg")).toBe(true);
+    expect(isSiloHttpRateLimitExempt("/robots.txt")).toBe(true);
+    expect(isSiloHttpRateLimitExempt("/admin")).toBe(true);
+    expect(isSiloHttpRateLimitExempt("/admin/org/para-26071100/members")).toBe(true);
+  });
+
+  it("still rate-limits APIs and auth", () => {
+    expect(isSiloHttpRateLimitExempt("/api/me")).toBe(false);
+    expect(isSiloHttpRateLimitExempt("/api/org/x/members")).toBe(false);
+    expect(isSiloHttpRateLimitExempt("/auth/feishu/x")).toBe(false);
+    expect(isSiloHttpRateLimitExempt("/auth/feishu/callback?code=1")).toBe(false);
+    expect(isSiloHttpRateLimitExempt("/")).toBe(false);
+  });
+});

hub/test/unit/skill-store.test.ts

@@ -2,7 +2,12 @@ import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promis
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
-import { importSkillDirectory, prepareRunSkillPlugin } from "../../src/agent/skillStore.js";
+import {
+  importSkillDirectory,
+  importSkillFromFiles,
+  prepareRunSkillPlugin,
+  readSkillFiles,
+} from "../../src/agent/skillStore.js";
 
 describe("content-addressed Agent skill store", () => {
   const roots: string[] = [];
@@ -55,6 +60,47 @@ describe("content-addressed Agent skill store", () => {
     })).rejects.toThrow(/content digest mismatch/);
   });
 
+  it("imports a skill from an in-memory file list and reads it back", async () => {
+    const root = await makeRoot();
+    const storeRoot = join(root, "store");
+    const manifest = `---\nname: web-skill\ndescription: Web uploaded\n---\n# web-skill\n`;
+    const files = [
+      { path: "SKILL.md", bytes: Buffer.from(manifest, "utf8") },
+      { path: "reference.md", bytes: Buffer.from("ref\n", "utf8") },
+    ];
+    const installed = await importSkillFromFiles({ files, storeRoot });
+    expect(installed).toMatchObject({ name: "web-skill", description: "Web uploaded" });
+    expect(installed.contentDigest).toMatch(/^[a-f0-9]{64}$/);
+
+    const readBack = await readSkillFiles({ storeRoot, contentDigest: installed.contentDigest });
+    expect(readBack).toHaveLength(2);
+    const byPath = Object.fromEntries(readBack.map((f) => [f.path, f.content]));
+    expect(byPath["SKILL.md"]).toContain("name: web-skill");
+    expect(byPath["reference.md"]).toBe("ref\n");
+  });
+
+  it("rejects file paths that escape the skill root", async () => {
+    const root = await makeRoot();
+    const storeRoot = join(root, "store");
+    const manifest = `---\nname: escape\ndescription: test\n---\n# escape\n`;
+    const files = [
+      { path: "SKILL.md", bytes: Buffer.from(manifest, "utf8") },
+      { path: "../escape.md", bytes: Buffer.from("x", "utf8") },
+    ];
+    await expect(importSkillFromFiles({ files, storeRoot })).rejects.toThrow(/must not escape/);
+  });
+
+  it("rejects duplicate file paths in importSkillFromFiles", async () => {
+    const root = await makeRoot();
+    const storeRoot = join(root, "store");
+    const manifest = `---\nname: dup\ndescription: test\n---\n# dup\n`;
+    const files = [
+      { path: "SKILL.md", bytes: Buffer.from(manifest, "utf8") },
+      { path: "SKILL.md", bytes: Buffer.from(manifest, "utf8") },
+    ];
+    await expect(importSkillFromFiles({ files, storeRoot })).rejects.toThrow(/duplicate skill file path/);
+  });
+
   async function makeRoot(): Promise<string> {
     const root = await mkdtemp(join(tmpdir(), "cph-skill-store-"));
     roots.push(root);

spec/Spec/System.lean

@@ -10,6 +10,7 @@ import Spec.System.Agent.Run
 import Spec.System.Agent.AgentRole
 import Spec.System.Agent.Memory
 import Spec.System.Agent.AgentSurface
+import Spec.System.Agent.Usage
 import Spec.System.Lock
 import Spec.System.Permission
 import Spec.System.PermissionGrant
@@ -39,11 +40,14 @@ likec4 已画出结构;这里补语义:
 - `Memory` —— 按需上下文:锚点类别(ADR-0003)+ MCP 工具按 run/project 上下文授权。
 - `AgentSurface` —— agent 执行面被 run 的工作区所界定(ADR-0018);与 Lock 正交——
   Lock 限定并发,Surface 限定波及面。机制 OPEN。
+- `Usage` —— Run 内 append-only 用量计量事实账本(ADR-0026);主模型 completion、
+  外部能力调用、代理网关旁路共用同一账本。fact 不持锁、不跨 run;`costUsd = none`
+  表示未知而非零(ADR-0022)。Run 上的 cost/token 标量是其 rollup cache。
 - `Permission` —— read⊂edit⊂manage 角色体系、能力推导、单调性;force-release 在格外。
 - `PermissionGrant` —— grant(resource×principal×role)与 settings(六 policy 旋钮)
   (ADR-0004);组合规则 OPEN。
 - `Audit` —— customer Project/Run 审计从简(内容 OPEN);Platform Audit 由
   `PlatformAdministration` 独立承载。
 
-标识符见 `Spec.Prelude`。决策出处:ADR-0001..0004, 0018, 0020..0024。
+标识符见 `Spec.Prelude`。决策出处:ADR-0001..0004, 0018, 0020..0026。
 -/

spec/Spec/System/Agent/Usage.lean

@@ -0,0 +1,92 @@
+import Spec.Prelude
+
+/-!
+# Usage —— Run 内用量计量事实账本(ADR-0026)
+
+一次 `AgentRun` 内可能产生**多条**可计费消耗:主模型 completion、外部能力调用
+(PDF→MD bundle、音视频转写等)、或代理网关侧旁路调用。这些消耗**不**是子 Run——
+它们不持项目锁、不占 session 语义、不复用 `AgentRun` 状态机。它们是 Run 内的
+append-only **计量事实**(`UsageFact`)。
+
+`AgentRun` 上的 cost/token 标量是 facts 的派生 rollup cache,不是真相来源;真相在
+`UsageFact` 行。这一层抽象让"主模型"与"外部能力"两类消耗共享同一账本,而非给后者
+各开一种特化字段或 nested Run。
+
+核心不变式(`PINNED`, ADR-0022 + ADR-0026):
+
+- **append-only** —— fact 一旦写入只读不更不删;`costUsd` 修正走新 fact,不改旧行。
+- **`costUsd = none` 表示"未知",不是"零成本"** —— ADR-0022:missing provider cost
+  remains unknown rather than zero。聚合时不得把 none 当 0 求和。
+- **fact 不持锁、不跨 run** —— 它是 Run 内的副作用账本,不是又一次 `@bot` 生命周期。
+  外部能力调用亦同:它的语义边界是 `capabilityId` + `correlationId`,不是 `RunId`。
+- **价目回算是派生** —— `costSource = pricebookDerived` 时,`costUsd` 由
+  `occurredAt × (provider, model)` 查价目表派生;provider 实报(`providerReported`)
+  优先于派生。无价目可查时 `costSource = unknown`,`costUsd = none`。
+
+外部能力(capability)注册表、价目表(pricebook)、商业结算均 `OPEN`,pilot 不做
+(ADR-0021 仍 defer commercial billing)。本模块只 pin **账本结构与不变式**。
+-/
+
+namespace Spec.System.Agent
+
+variable (I : Identifiers) (Time Cost Quantity : Type)
+
+/-- 计量事实类型(`PINNED`, ADR-0026)。集合完整性 `OPEN`——新增 kind 须 surface,
+不得静默把外部消耗塞进既有 kind。 -/
+inductive UsageFactKind where
+  /-- 主 agent loop 的模型 completion(`PINNED`)。 -/
+  | modelCompletion
+  /-- 外部能力调用(`PINNED`;如 pdf_to_md_bundle、audio_video_to_text)。 -/
+  | externalCapability
+  /-- 代理网关侧旁路调用(`PINNED`;非主 loop 的模型调用,如嵌入工具内的子请求)。 -/
+  | toolProxy
+
+/-- 成本来源(`PINNED`, ADR-0026)。优先级:provider 实报 > 价目派生 > unknown。 -/
+inductive CostSource where
+  /-- provider/gateway 实报(`PINNED`)。 -/
+  | providerReported
+  /-- 用 `occurredAt × (provider, model)` 价目表派生(`PINNED`)。 -/
+  | pricebookDerived
+  /-- 缺失,而非零(`PINNED`;ADR-0022 missing cost ≠ zero)。 -/
+  | unknown
+
+/-- 一次可计费消耗的计量事实(`PINNED`, ADR-0026)。append-only;一次 run ≥0 条。
+
+字段分两组:**归属与时间**(run/occurredAt/kind)用于聚合与价目回算;
+**计量与成本**(tokens/quantity/unit/costUsd/costSource)用于账目本身。
+非 token 计量(页/秒/次)走 `quantity + unit`,与 token 并存而非取代。 -/
+structure UsageFact where
+  /-- 所属 run(`PINNED`;fact 不跨 run,fact 不持锁,ADR-0026)。 -/
+  run : I.RunId
+  /-- 消耗发生时刻(`PINNED`);价目回算依赖此字段而非 run.finishedAt,
+  因为外部能力可能早于 run 结束。 -/
+  occurredAt : Time
+  /-- 事实类型(`PINNED`, ADR-0026)。 -/
+  kind : UsageFactKind
+  /-- provider 标识(`PINNED`;如 openrouter、mineru、openai_whisper)。 -/
+  provider : String
+  /-- 模型标识(`OPEN`;非模型计费可为 none)。 -/
+  model : Option String
+  /-- 输入 tokens(`OPEN`;非 token 计量可为 none)。 -/
+  inputTokens : Option Nat
+  /-- 输出 tokens(`OPEN`)。 -/
+  outputTokens : Option Nat
+  /-- 非 token 计量数值(`OPEN`;如页数、音频秒数)。与 tokens 并存。 -/
+  quantity : Option Quantity
+  /-- 计量单位(`OPEN`;如 "pages"、"audio_seconds"、"invocations")。 -/
+  unit : Option String
+  /-- 成本(`PINNED`;none = 未知,非零,ADR-0022)。 -/
+  costUsd : Option Cost
+  /-- 成本来源(`PINNED`;costUsd ≠ none 时必填,costUsd = none 时为 `unknown`)。 -/
+  costSource : CostSource
+  /-- 外部能力标识(`OPEN`;kind = externalCapability 时填,如 pdf_to_md_bundle)。 -/
+  capabilityId : Option String
+  /-- 外部请求关联 id(`OPEN`;对账/幂等用,不参与聚合)。 -/
+  correlationId : Option String
+
+/-- Fact 的成本是否**已知**(`PINNED`, ADR-0026)。聚合 rollup 时,只对已知成本求和;
+未知成本的 fact 不贡献 0,而是让汇总保持未知(若所有 fact 均未知)或部分未知。 -/
+def UsageFact.HasKnownCost (fact : UsageFact I Time Cost Quantity) : Prop :=
+  fact.costUsd ≠ none
+
+end Spec.System.Agent