oceanbase · PsiACE · Aug 29, 2026 · Aug 29, 2026
diff --git a/docs/en/docs/how-to/configure-workbuddy.md b/docs/en/docs/how-to/configure-workbuddy.md
@@ -8,7 +8,7 @@ description: Install the PowerContext WorkBuddy hooks and control its local beha
 ## Prerequisites
 
 - A running PowerContext installation. Install the CLI and local Server from the same `master` revision used below:
-  `uv tool install "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"`.
+  `uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"`.
   Start the Server with `powercontext server run`.
 - WorkBuddy with user-level hooks, MCP, and Skills support (the desktop app).
 - Python 3.11 or newer on `PATH` for the hook process.

diff --git a/docs/en/docs/how-to/deploy-server.md b/docs/en/docs/how-to/deploy-server.md
@@ -97,6 +97,9 @@ docker run --rm \
 
 Clients then send `Authorization: Bearer <token>`. The liveness and readiness endpoints remain public so an
 orchestrator can probe them. API, MCP, metrics, OpenAPI, and interactive API documentation require authentication.
+The Server's web-page shells and static assets remain public so they can show a sign-in form; they do not return
+protected data without the token. Open the Dashboard, Skills, Review, or Handoff Report page and enter the same token
+there. It remains in the current browser tab's session storage rather than being added to the URL.
 
 ## Check the deployment
 

diff --git a/docs/en/docs/how-to/full-capability-runtime.md b/docs/en/docs/how-to/full-capability-runtime.md
@@ -55,7 +55,7 @@ project:quickstart
 #### 1. Install
 
 ```bash
-uv tool install "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
+uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
 ```
 
 #### 2. Generate the configuration

diff --git a/docs/en/docs/how-to/install-and-run.md b/docs/en/docs/how-to/install-and-run.md
@@ -11,12 +11,13 @@ You need Python 3.11 or newer, Git, and [`uv`](https://docs.astral.sh/uv/) on ma
 PowerContext directly from a Git ref:
 
 ```bash
-uv tool install "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
+uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
 ```
 
 The command does not leave a repository checkout for you to manage. Git uses its normal credential configuration,
 including credential helpers and SSH settings. For an SSH-based install, replace the HTTPS URL with the Git URL
-approved for your environment.
+approved for your environment. `--force` also refreshes an existing tool from the current commit behind the selected
+Git ref; without it, `uv` may report the same requirement as already installed without fetching a newer `master`.
 
 To install a tested branch or tag, replace `master` after the final `@`. Use the same ref when configuring integrations:
 

diff --git a/docs/en/docs/how-to/trace-with-phoenix.md b/docs/en/docs/how-to/trace-with-phoenix.md
@@ -25,7 +25,7 @@ running. Pin an explicit tag so the endpoint and UI layout match this guide.
 Recording and export require the `tracing-otlp` extra:
 
 ```bash
-uv tool install "powercontext[cli,server,tracing-otlp] @ git+https://github.com/oceanbase/powercontext.git@master"
+uv tool install --force "powercontext[cli,server,tracing-otlp] @ git+https://github.com/oceanbase/powercontext.git@master"
 ```
 
 Without this extra, enabling tracing fails at startup with an explicit error instead of silently dropping spans.

diff --git a/docs/en/docs/reference/configuration.md b/docs/en/docs/reference/configuration.md
@@ -73,8 +73,14 @@ Server settings use the `POWERCONTEXT_SERVER_` prefix.
 | `POWERCONTEXT_SERVER_RUNTIME_MEMORY_RERANK_ENABLED` | `false` | Apply listwise reranking after coarse Memory retrieval |
 | `POWERCONTEXT_SERVER_RUNTIME_MEMORY_RERANK_CANDIDATE_LIMIT` | `30` | Coarse candidate pool supplied to the reranker |
 | `POWERCONTEXT_SERVER_RUNTIME_SCHEDULE_SECONDS` | unset | Scheduler interval; unset disables scheduling |
-| `POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL` | unset | Pydantic AI model identifier for Memory extraction |
-| `POWERCONTEXT_SERVER_INFERENCE_GENERATION_TIMEOUT_SECONDS` | `30` | Generation timeout |
+| `POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL` | unset | Pydantic AI model used by configured extraction, generation, Handoff, and reranking operations |
+| `POWERCONTEXT_SERVER_INFERENCE_GENERATION_TIMEOUT_SECONDS` | `30` | Timeout in seconds for one structured generation operation |
+| `POWERCONTEXT_SERVER_INFERENCE_GENERATION_MAX_REQUESTS` | `2` | Maximum provider requests for one structured generation operation, including retries |
+| `POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_MODEL` | unset | Pydantic AI embedding model; requires profile ID and dimension |
+| `POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_PROFILE_ID` | unset | Stable identity for the model, dimension, and normalization used by the vector index |
+| `POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_DIMENSION` | unset | Positive output dimension requested from and validated against the embedding model |
+| `POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_NORMALIZATION` | `unit` | Vector normalization: `unit` or `none` |
+| `POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_TIMEOUT_SECONDS` | `30` | Timeout in seconds for one embedding request |
 | `POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_BATCH_SIZE` | `10` | Maximum texts sent in one embedding request |
 | `POWERCONTEXT_SERVER_RUNTIME_EXPERIENCE_SCHEDULE_SECONDS` | unset | Experience incubation interval; unset disables that job |
 | `POWERCONTEXT_SERVER_EXTERNAL_SKILLS` | unset | JSON object containing the host identity and explicit Agent Skill targets |
@@ -98,6 +104,11 @@ The Dashboard is enabled by default and shares the Server listener and port with
 configured, the page shows an empty state. Dashboard initialization failures are logged with their direct cause and do
 not prevent the Server HTTP API, MCP, or health checks from starting.
 
+When bearer authentication is enabled, the HTML shells at `/`, `/skills`, `/reviews`, and `/handoff-reports`, plus
+their static assets, remain public so the browser can render the sign-in form. Data requests stay protected. Enter the
+Server token in that form; the browser keeps it only in the current tab's session storage. Disable both Dashboard and
+Handoff Report if even these sign-in pages must not be exposed.
+
 Handoff Report is independently enabled by default at `/handoff-reports`. When no scope contains a committed Handoff,
 it shows a data-free template preview. See [Use Handoff Report](../how-to/use-handoff-report.md) for scope discovery,
 inspection, Revision writes, and export.

diff --git a/docs/en/docs/reference/http-api.md b/docs/en/docs/reference/http-api.md
@@ -19,7 +19,9 @@ With a local unauthenticated Server running, open:
 The checked-in source of truth is
 [`openapi/powercontext.yaml`](https://github.com/oceanbase/powercontext/blob/master/openapi/powercontext.yaml).
 Use it when generating a client or reviewing every request and response field. When Server authentication is enabled,
-the three discovery routes require the same bearer token as other protected routes.
+the three discovery routes require the same bearer token as other protected routes. A browser address bar cannot add
+that header: use a trusted proxy or browser setup that injects it, or download `/openapi.json` with an authenticated
+command after setting the variables below. Never put the token in the URL.
 
 ## Authenticate requests
 
@@ -41,6 +43,15 @@ Omit `--header "$POWERCONTEXT_AUTH_HEADER"` when authentication is disabled. The
 `/health/ready` endpoints are always public. See [Deploy the Server](../how-to/deploy-server.md) before allowing remote
 access.
 
+For an authenticated Server, download the exact contract served by that process with:
+
+```bash
+curl --fail \
+  --header "$POWERCONTEXT_AUTH_HEADER" \
+  --output powercontext-openapi.json \
+  "$POWERCONTEXT_URL/openapi.json"
+```
+
 ## Store and search one Memory
 
 Choose a stable `scope_id` for the project or tenant. Reuse it across sessions; a session ID is not a durable project
@@ -49,7 +60,7 @@ identity.
 Store one already-curated Memory entry:
 
 ```bash
-curl --fail-with-body \
+curl --fail \
   --request POST \
   --header 'Content-Type: application/json' \
   --header "$POWERCONTEXT_AUTH_HEADER" \
@@ -67,7 +78,7 @@ specific immutable revision.
 Search active entries in the same scope:
 
 ```bash
-curl --fail-with-body \
+curl --fail \
   --request POST \
   --header 'Content-Type: application/json' \
   --header "$POWERCONTEXT_AUTH_HEADER" \

diff --git a/docs/en/docs/tutorials/codex-quickstart.md b/docs/en/docs/tutorials/codex-quickstart.md
@@ -18,7 +18,7 @@ repository with the credentials already configured on your machine.
 Run these commands from any directory:
 
 ```bash
-uv tool install "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
+uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
 powercontext setup codex --source oceanbase/powercontext --ref master
 ```
 

diff --git a/docs/en/rfcs/README.md b/docs/en/rfcs/README.md
@@ -43,7 +43,7 @@ Useful preparatory steps include:
 
 ## The RFC process
 
-- Fork the [PowerContext repo](https://github.com/oceanbase/powercontext) and create a branch from `main`.
+- Fork the [PowerContext repo](https://github.com/oceanbase/powercontext) and create a branch from `master`.
 - Copy [`0000_example.md`](0000_example.md) to `0000-my-feature.md`, where `my-feature` is descriptive.
 - Do not assign an RFC number before opening the pull request. The RFC number should match the pull request number.
 - Submit a pull request containing the RFC document under `docs/en/rfcs/` and keep its Chinese translation in sync.

diff --git a/docs/zh/docs/how-to/configure-workbuddy.md b/docs/zh/docs/how-to/configure-workbuddy.md
@@ -8,7 +8,7 @@ description: 安装 PowerContext WorkBuddy hooks 并控制其本地行为。
 ## 前置条件
 
 - 已安装并可运行的 PowerContext。从与下方插件相同的 `master` revision 安装 CLI 和本地 Server：
-  `uv tool install "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"`。
+  `uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"`。
   然后执行 `powercontext server run` 启动 Server。
 - 支持用户级 hooks、MCP 和 Skills 的 WorkBuddy 桌面应用。
 - 用于执行 hook 进程的 Python 3.11 或更新版本，且已加入 `PATH`。

diff --git a/docs/zh/docs/how-to/deploy-server.md b/docs/zh/docs/how-to/deploy-server.md
@@ -95,6 +95,9 @@ docker run --rm \
 
 此后客户端需要发送 `Authorization: Bearer <token>`。liveness 和 readiness endpoint 保持公开，便于编排系统探测；
 API、MCP、metrics、OpenAPI 和交互式 API 文档都需要鉴权。
+Server 的网页外壳和静态资源仍保持公开，以便显示登录表单；未提供 token 时不会返回受保护数据。打开 Dashboard、
+Skills、Review 或 Handoff Report 页面后，在表单中输入同一个 token。浏览器会把它保存在当前标签页的 session storage
+中，而不是加入 URL。
 
 ## 检查部署
 

diff --git a/docs/zh/docs/how-to/full-capability-runtime.md b/docs/zh/docs/how-to/full-capability-runtime.md
@@ -55,7 +55,7 @@ project:quickstart
 #### 1. 安装
 
 ```bash
-uv tool install "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
+uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
 ```
 
 #### 2. 生成配置

diff --git a/docs/zh/docs/how-to/install-and-run.md b/docs/zh/docs/how-to/install-and-run.md
@@ -11,11 +11,12 @@ description: 从 Git 安装 PowerContext，并运行本地 Server。
 [`uv`](https://docs.astral.sh/uv/)，然后从指定 Git ref 直接安装 PowerContext：
 
 ```bash
-uv tool install "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
+uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
 ```
 
 该命令不会留下需要自行管理的仓库工作副本。Git 会沿用本机的凭据配置，包括 credential helper 和 SSH 设置。
-如需使用 SSH，请把 HTTPS URL 换成当前环境允许的 Git URL。
+如需使用 SSH，请把 HTTPS URL 换成当前环境允许的 Git URL。`--force` 还会从所选 Git ref 当前指向的 commit
+刷新已安装工具；如果不加该参数，`uv` 可能只提示相同 requirement 已安装，而不会获取更新后的 `master`。
 
 安装指定分支或 tag 时，替换最后一个 `@` 后的 `master`。配置集成时应使用同一个 ref：
 

diff --git a/docs/zh/docs/how-to/trace-with-phoenix.md b/docs/zh/docs/how-to/trace-with-phoenix.md
@@ -24,7 +24,7 @@ Phoenix 的 UI 和 OTLP HTTP 接收端都在端口 `6006`。打开 <http://local
 recording 和 export 需要 `tracing-otlp` extra：
 
 ```bash
-uv tool install "powercontext[cli,server,tracing-otlp] @ git+https://github.com/oceanbase/powercontext.git@master"
+uv tool install --force "powercontext[cli,server,tracing-otlp] @ git+https://github.com/oceanbase/powercontext.git@master"
 ```
 
 缺少该 extra 时，启用 tracing 会在启动阶段直接报错，而不是静默丢弃 span。

diff --git a/docs/zh/docs/reference/configuration.md b/docs/zh/docs/reference/configuration.md
@@ -70,8 +70,14 @@ Server 配置使用 `POWERCONTEXT_SERVER_` 前缀。
 | `POWERCONTEXT_SERVER_RUNTIME_MEMORY_RERANK_ENABLED` | `false` | 在 Memory 粗召回后应用 listwise rerank |
 | `POWERCONTEXT_SERVER_RUNTIME_MEMORY_RERANK_CANDIDATE_LIMIT` | `30` | 交给 reranker 的粗排候选池大小 |
 | `POWERCONTEXT_SERVER_RUNTIME_SCHEDULE_SECONDS` | 未设置 | Scheduler 间隔；未设置即不启用 |
-| `POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL` | 未设置 | 用于 Memory extraction 的 Pydantic AI 模型标识 |
-| `POWERCONTEXT_SERVER_INFERENCE_GENERATION_TIMEOUT_SECONDS` | `30` | Generation 超时 |
+| `POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL` | 未设置 | 配置的 extraction、generation、Handoff 和 rerank 操作共用的 Pydantic AI 模型 |
+| `POWERCONTEXT_SERVER_INFERENCE_GENERATION_TIMEOUT_SECONDS` | `30` | 单次结构化 generation 操作的超时秒数 |
+| `POWERCONTEXT_SERVER_INFERENCE_GENERATION_MAX_REQUESTS` | `2` | 单次结构化 generation 操作最多发起的 provider 请求数，包含重试 |
+| `POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_MODEL` | 未设置 | Pydantic AI embedding model；必须同时设置 profile ID 和 dimension |
+| `POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_PROFILE_ID` | 未设置 | vector index 使用的模型、dimension 和 normalization 的稳定标识 |
+| `POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_DIMENSION` | 未设置 | 向 embedding model 请求并校验的正整数输出维度 |
+| `POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_NORMALIZATION` | `unit` | vector normalization：`unit` 或 `none` |
+| `POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_TIMEOUT_SECONDS` | `30` | 单次 embedding 请求的超时秒数 |
 | `POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_BATCH_SIZE` | `10` | 单次 embedding 请求最多发送的文本数量 |
 | `POWERCONTEXT_SERVER_RUNTIME_EXPERIENCE_SCHEDULE_SECONDS` | 未设置 | Experience 孵化间隔；未设置即不启用该 job |
 | `POWERCONTEXT_SERVER_EXTERNAL_SKILLS` | 未设置 | 包含 host identity 和显式 Agent Skill targets 的 JSON object |
@@ -93,6 +99,10 @@ Python Client 和 CLI 对出站请求应用相同规则：配置的明文 `http:
 Dashboard 默认启用，并与 HTTP API、MCP 共用监听地址和端口。默认未配置 scope，页面会显示空状态；Dashboard
 初始化失败只记录包含直接原因的 warning，不影响 Server 的 HTTP API、MCP 和健康检查启动。
 
+启用 Bearer 鉴权后，`/`、`/skills`、`/reviews`、`/handoff-reports` 的 HTML 外壳及其静态资源仍保持公开，以便
+浏览器渲染登录表单；数据请求仍受鉴权保护。在表单中输入 Server token 后，浏览器只把它保存在当前标签页的 session
+storage 中。如果连这些登录页也不能暴露，应同时关闭 Dashboard 和 Handoff Report。
+
 Handoff Report 独立默认启用，路径为 `/handoff-reports`。没有任何 scope 包含 committed Handoff 时，页面显示无数据
 模板预览。Scope discovery、检查、Revision 写入和导出步骤见[使用 Handoff Report](../how-to/use-handoff-report.md)。
 

diff --git a/docs/zh/docs/reference/http-api.md b/docs/zh/docs/reference/http-api.md
@@ -18,7 +18,8 @@ HTTP API 是访问 PowerContext Server 的语言无关接口。默认 base URL
 仓库中的契约源文件是
 [`openapi/powercontext.yaml`](https://github.com/oceanbase/powercontext/blob/master/openapi/powercontext.yaml)。
 生成客户端或检查全部请求、响应字段时以它为准。启用 Server 鉴权后，这三个发现路由与其他受保护路由一样需要 Bearer
-token。
+token。浏览器地址栏无法添加该 header；应使用可信的代理或浏览器配置注入 header，或者设置下方变量后，通过带鉴权的
+命令下载 `/openapi.json`。不要把 token 放进 URL。
 
 ## 请求鉴权
 
@@ -38,14 +39,23 @@ POWERCONTEXT_AUTH_HEADER="Authorization: Bearer ${POWERCONTEXT_CLIENT_API_TOKEN}
 未启用鉴权时，请去掉 `--header "$POWERCONTEXT_AUTH_HEADER"`。`/health/live` 和 `/health/ready` 始终公开。
 允许远程访问前，请先阅读[部署 Server](../how-to/deploy-server.md)。
 
+Server 启用鉴权时，可以用以下命令下载该进程实际提供的契约：
+
+```bash
+curl --fail \
+  --header "$POWERCONTEXT_AUTH_HEADER" \
+  --output powercontext-openapi.json \
+  "$POWERCONTEXT_URL/openapi.json"
+```
+
 ## 保存并搜索一条 Memory
 
 为项目或租户选择稳定的 `scope_id`，并在不同会话中复用。会话 ID 不是持久的项目身份。
 
 保存一条已经整理好的 Memory：
 
 ```bash
-curl --fail-with-body \
+curl --fail \
   --request POST \
   --header 'Content-Type: application/json' \
   --header "$POWERCONTEXT_AUTH_HEADER" \
@@ -62,7 +72,7 @@ curl --fail-with-body \
 在同一个 scope 中搜索 active entry：
 
 ```bash
-curl --fail-with-body \
+curl --fail \
   --request POST \
   --header 'Content-Type: application/json' \
   --header "$POWERCONTEXT_AUTH_HEADER" \

diff --git a/docs/zh/docs/tutorials/codex-quickstart.md b/docs/zh/docs/tutorials/codex-quickstart.md
@@ -18,7 +18,7 @@ Memory。
 在任意目录执行：
 
 ```bash
-uv tool install "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
+uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
 powercontext setup codex --source oceanbase/powercontext --ref master
 ```
 

diff --git a/docs/zh/rfcs/README.md b/docs/zh/rfcs/README.md
@@ -43,7 +43,7 @@ RFC（request for comments）流程为重大变更提供一致路径，使维护
 
 ## RFC 流程
 
-- Fork [PowerContext repo](https://github.com/oceanbase/powercontext)，并从 `main` 创建分支。
+- Fork [PowerContext repo](https://github.com/oceanbase/powercontext)，并从 `master` 创建分支。
 - 将 [`0000_example.md`](0000_example.md) 复制为 `0000-my-feature.md`，其中 `my-feature` 应具有描述性。
 - 打开 pull request 前不要分配 RFC 编号。RFC 编号应与 pull request 编号一致。
 - 提交包含 RFC 文档的 pull request，文档位于 `docs/en/rfcs/` 下，并同步维护 `docs/zh/rfcs/` 中的中文翻译。

diff --git a/integrations/dsh/README.md b/integrations/dsh/README.md
@@ -5,7 +5,7 @@
 Install the PowerContext tool first, then configure the plugin from the same Git ref:
 
 ```bash
-uv tool install "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
+uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
 powercontext setup dsh --source oceanbase/powercontext --ref master
 powercontext server run
 ```

diff --git a/integrations/opencode/README.md b/integrations/opencode/README.md
@@ -5,7 +5,7 @@
 Install PowerContext and the plugin from the same Git ref:
 
 ```bash
-uv tool install "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
+uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
 powercontext setup opencode --source oceanbase/powercontext --ref master
 powercontext server run
 opencode

diff --git a/src/powercontext/cli/app.py b/src/powercontext/cli/app.py
@@ -26,7 +26,7 @@
 
 COMMAND_PROVIDER_GROUP = "powercontext.cli"
 HELP_OPTION_NAMES = ("-h", "--help")
-DOCUMENTATION_URL = "https://github.com/oceanbase/powercontext/tree/main/docs/en/docs"
+DOCUMENTATION_URL = "https://github.com/oceanbase/powercontext/tree/master/docs/en/docs"
 ISSUES_URL = "https://github.com/oceanbase/powercontext/issues"