From 9940c2cc82526ca9b1d72cea25768b7e049549d2 Mon Sep 17 00:00:00 2001
From: CX33071 <3541053286@qq.com>
Date: Sat, 17 Oct 2026 19:34:29 +0800
Subject: [PATCH 1/4] docs:add manual startup guides

---
 README.md                                |   4 +-
 README_CN.md                             |   4 +-
 docs/en/docs/get-started/manual-start.md | 278 +++++++++++++++++++++++
 docs/en/docs/get-started/meta.json       |   1 +
 docs/zh/docs/get-started/manual-start.md | 278 +++++++++++++++++++++++
 docs/zh/docs/get-started/meta.json       |   1 +
 6 files changed, 564 insertions(+), 2 deletions(-)
 create mode 100644 docs/en/docs/get-started/manual-start.md
 create mode 100644 docs/zh/docs/get-started/manual-start.md

diff --git a/README.md b/README.md
index aa344e1b5d..8393f8aa5c 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@
 
 *[English](README.md) · [中文](README_CN.md) · [日本語](README_JP.md)*
 
-[Website](https://powercontext.oceanbase.io/) · [Quickstart](https://powercontext.oceanbase.io/en/docs/get-started/quickstart/) · [Integrations](https://powercontext.oceanbase.io/en/docs/integrations/) · [Benchmarks](https://powercontext.oceanbase.io/en/benchmarks/) · [Interfaces](https://powercontext.oceanbase.io/en/docs/develop/interfaces/)
+[Website](https://powercontext.oceanbase.io/) · [Quickstart](https://powercontext.oceanbase.io/en/docs/get-started/quickstart/) · [Manual startup](docs/en/docs/get-started/manual-start.md) · [Integrations](https://powercontext.oceanbase.io/en/docs/integrations/) · [Benchmarks](https://powercontext.oceanbase.io/en/benchmarks/) · [Interfaces](https://powercontext.oceanbase.io/en/docs/develop/interfaces/)
 
 ## Quick start
 
@@ -34,6 +34,8 @@ Choose the path that matches your goal:
 | Process Sources automatically and use Topic Memory or semantic retrieval | **Full memory** | Separate Generation and Embedding API credentials; schedules and Scope policies still apply |
 | Learn the core workflows in Python | The first seven Jupyter tutorials | A repository checkout and `uv`; no model or API key |
 
+If you want to manually configure and start PowerContext, see the [manual startup guide](docs/en/docs/get-started/manual-start.md) before following the quick-start instructions below.
+
 ### 1. Install and run the wizard
 
 ```bash
diff --git a/README_CN.md b/README_CN.md
index da0b21fc15..90cd0546be 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -9,7 +9,7 @@
 
 *[English](README.md) · [中文](README_CN.md) · [日本語](README_JP.md)*
 
-[网站](https://powercontext.oceanbase.io/zh/) · [快速开始](https://powercontext.oceanbase.io/zh/docs/get-started/quickstart/) · [接入 Agent](https://powercontext.oceanbase.io/zh/docs/integrations/) · [评测](https://powercontext.oceanbase.io/zh/benchmarks/) · [接口](https://powercontext.oceanbase.io/zh/docs/develop/interfaces/)
+[网站](https://powercontext.oceanbase.io/zh/) · [快速开始](https://powercontext.oceanbase.io/zh/docs/get-started/quickstart/) · [手动启动](docs/zh/docs/get-started/manual-start.md) · [接入 Agent](https://powercontext.oceanbase.io/zh/docs/integrations/) · [评测](https://powercontext.oceanbase.io/zh/benchmarks/) · [接口](https://powercontext.oceanbase.io/zh/docs/develop/interfaces/)
 
 ## 快速开始
 
@@ -34,6 +34,8 @@ PowerContext 1.3.0 包含交互式配置向导。需要 Python 3.11+、Git 和
 | 自动处理 Source，使用 Topic Memory 或语义检索 | **完整记忆能力** | 独立的 Generation、Embedding API 凭据；仍受调度和 Scope 策略影响 |
 | 用 Python 学习核心工作流 | 前七篇 Jupyter 教程 | 仓库 checkout 和 `uv`；不需要模型或 API Key |
 
+如果希望手动配置并启动 PowerContext，请先查看[手动启动指南](docs/zh/docs/get-started/manual-start.md)，再按照下面的快速开始步骤操作。
+
 ### 1. 安装并运行配置向导
 
 ```bash
diff --git a/docs/en/docs/get-started/manual-start.md b/docs/en/docs/get-started/manual-start.md
new file mode 100644
index 0000000000..ad93958b30
--- /dev/null
+++ b/docs/en/docs/get-started/manual-start.md
@@ -0,0 +1,278 @@
+---
+title: Manually start PowerContext
+description: Configure and start the PowerContext Server manually without the setup wizard, connect Codex, and verify Memory.
+---
+
+# Manually start PowerContext
+
+This page explains how to configure and start the PowerContext Server without using the powercontext config init setup wizard, then bind Codex to a Scope.
+
+Use this page if you want to understand each step, troubleshoot configuration, or control the Server address, port, Dashboard, and authentication yourself. If you prefer the interactive setup wizard, see [Quick Start](quickstart.md).
+
+## Manual startup versus Quick Start
+
+Quick Start uses the setup wizard:
+
+~~~text
+config init → generate .env → start Server → create Scope → connect Agent
+~~~
+
+Manual startup does not run config init. You prepare the environment variables or configuration file yourself:
+
+~~~text
+write configuration → validate → server run → check Server → create Scope → bind Agent
+~~~
+
+Manual startup does not mean compiling PowerContext from source. It means running PowerContext without relying on the configuration wizard and choosing the Server settings yourself.
+
+## Prerequisites
+
+You need Python 3.11 or newer, Git, [uv](https://docs.astral.sh/uv/getting-started/installation/), and an Agent CLI such as Codex CLI if you want to connect an Agent.
+
+~~~bash
+python3 --version
+git --version
+uv --version
+~~~
+
+## 1. Install PowerContext
+
+If uv is not installed, run:
+
+~~~bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source "$HOME/.local/bin/env"
+~~~
+
+Install the PowerContext CLI and local Server:
+
+~~~bash
+uv tool install --force "powercontext[cli,server]==1.3.0"
+powercontext --version
+powercontext --help
+~~~
+
+## 2. Stop a possibly running personal service
+
+If you previously ran powercontext service install, a personal background Server may already be running. It may occupy the default port and make it unclear which Server you are checking.
+
+~~~bash
+powercontext service status
+~~~
+
+If the personal service is running, stop it:
+
+~~~bash
+powercontext service stop
+~~~
+
+This stops the personal service and prevents automatic activation while keeping its configuration and data.
+
+## 3. Create a manual configuration file
+
+~~~bash
+mkdir -p ~/powercontext-manual
+cd ~/powercontext-manual
+nano manual.env
+~~~
+
+Put the following values in manual.env:
+
+~~~dotenv
+POWERCONTEXT_SERVER_HTTP_HOST=127.0.0.1
+POWERCONTEXT_SERVER_HTTP_PORT=18080
+POWERCONTEXT_SERVER_DASHBOARD_ENABLED=true
+POWERCONTEXT_SERVER_ACCESS_MODE=disabled
+~~~
+
+The settings mean:
+
+| Setting | Purpose |
+| --- | --- |
+| POWERCONTEXT_SERVER_HTTP_HOST | Listen only on the local machine |
+| POWERCONTEXT_SERVER_HTTP_PORT | Listen on port 18080 |
+| POWERCONTEXT_SERVER_DASHBOARD_ENABLED | Enable the Dashboard |
+| POWERCONTEXT_SERVER_ACCESS_MODE | Disable authentication for local testing |
+
+This configuration does not specify a database or models, so it uses the default SQLite database and does not enable inference capabilities.
+
+## 4. Validate the manual configuration
+
+~~~bash
+env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
+  powercontext config validate \
+  --env-file ~/powercontext-manual/manual.env
+~~~
+
+A successful command prints Configuration is valid. This step only validates the configuration; it does not start the Server.
+
+## 5. Start the Server manually
+
+~~~bash
+env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
+  powercontext server run \
+  --env-file ~/powercontext-manual/manual.env
+~~~
+
+Keep this terminal open. A successful startup looks similar to:
+
+~~~text
+PowerContext Server is ready
+Uvicorn running on http://127.0.0.1:18080
+~~~
+
+Press Ctrl-C to stop the foreground Server. If Generation and Embedding models are not configured, PowerContext prints a notice, but explicit Basic Memory saves and recall still work.
+
+## 6. Open the Dashboard
+
+Open the following address in a browser:
+
+~~~text
+http://127.0.0.1:18080/dashboard/home
+~~~
+
+Authentication is disabled, so the page can be opened directly from the local machine. An empty Dashboard on the first visit is expected.
+
+## 7. Check the Server
+
+Keep the Server running and open another terminal:
+
+~~~bash
+env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
+  POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \
+  powercontext doctor
+~~~
+
+Continue with:
+
+~~~bash
+env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
+  POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \
+  powercontext ready
+~~~
+
+~~~bash
+env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
+  POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \
+  powercontext capabilities
+~~~
+
+Expected output includes:
+
+~~~text
+server liveness: ok - http://127.0.0.1:18080
+server readiness: ok - http://127.0.0.1:18080
+access_mode: disabled
+database: ready
+~~~
+
+doctor checks the installation, Server liveness, and readiness. ready checks whether the Server can provide requests. capabilities shows the currently enabled capabilities.
+
+## 8. Create a Scope manually
+
+A Scope is an isolated space for project context. It separates Sources, Memory, Topic Memory, Handoffs, and Agent recall data.
+
+Use the Python Client to call the Server and create a Scope manually. Keep the Server running and execute the following in another terminal:
+
+~~~bash
+cd ~/powercontext-manual
+POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \
+uv run --with "powercontext[client]==1.3.0" python - <<'PY'
+import asyncio
+import os
+from powercontext.client import PowerContextClient
+from powercontext.http import CreateScopeRequest
+
+async def main():
+    async with PowerContextClient(os.environ["POWERCONTEXT_CLIENT_SERVER_URL"]) as client:
+        scope = await client.create_scope(
+            CreateScopeRequest(
+                title="manual-powercontext-demo",
+                summary="Scope created during manual setup",
+                idempotency_key="manual-powercontext-demo-v1",
+            )
+        )
+        print("scope_id:", scope.scope_id)
+
+asyncio.run(main())
+PY
+~~~
+
+The Server returns the real scope_id. Use this ID when binding the Agent; do not construct an ID from the Scope title.
+
+## 9. Bind the Codex Agent
+
+Set the real Scope ID in the current terminal:
+
+~~~bash
+export POWERCONTEXT_CODEX_SCOPE_ID=replace-with-the-scope-id-returned-by-the-server
+~~~
+
+Install the Codex plugin matching the Server version and point it to the manually started Server:
+
+~~~bash
+powercontext setup codex \
+  --ref powercontext-v1.3.0 \
+  --server-url http://127.0.0.1:18080
+powercontext doctor codex
+~~~
+
+The checks should confirm that the plugin, MCP, and tool discovery are working. Installing the plugin does not start the Server, so the Server terminal must remain open.
+
+## 10. Verify explicit Memory and cross-session recall
+
+Start a new Codex session from a terminal where POWERCONTEXT_CODEX_SCOPE_ID is set:
+
+~~~bash
+codex
+~~~
+
+Send a message that explicitly asks Codex to save a decision:
+
+~~~text
+Please save the following decision to PowerContext:
+
+The Aurora project uses uv to manage Python dependencies and .env for configuration. The first phase will be deployed on a Linux server.
+~~~
+
+Exit Codex, start a new session with the same Scope, and ask:
+
+~~~text
+Please retrieve the Aurora project's dependency management and deployment decision from PowerContext.
+~~~
+
+If the Agent retrieves the same content and shows the Memory as active with its source and revision, manual startup, Scope binding, explicit saving, and cross-session recall have all been verified.
+
+## Capability boundaries
+
+This page does not configure Generation or Embedding models. It therefore verifies explicit Memory, full-text search, and cross-session recall, but it does not verify automatic Memory extraction or automatic generation of Topic Memory, Experience, or Skill. To enable those capabilities, see [Configure models](configure-models.md).
+
+## Troubleshooting
+
+### capabilities shows extraction disabled
+
+This means that Generation and Embedding models are not configured. It does not prevent explicit Basic Memory saves and recall.
+
+### capabilities returns 401
+
+The Server is usually enforcing authentication while the client has no Token. Confirm that manual.env contains POWERCONTEXT_SERVER_ACCESS_MODE=disabled and use env -i to avoid inheriting old environment variables.
+
+### The check connects to port 8000 instead of 18080
+
+Set the client address explicitly:
+
+~~~bash
+POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 powercontext ready
+~~~
+
+### The Dashboard has no data
+
+An empty Dashboard on the first visit is expected. Write a Source or Memory through an Agent or API, and confirm that the Dashboard and Agent use the same Server and Scope.
+
+## Related documentation
+
+- [Quick Start](quickstart.md): use the setup wizard for a complete memory walkthrough;
+- [Configure the Server environment](configure-server-environment.md): learn about configuration files and environment variables;
+- [Configure models](configure-models.md): enable automatic extraction and vector retrieval;
+- [Deploy the Server](../operate/deploy-server.md): run a personal background service or remote Server;
+- [Troubleshoot](../operate/troubleshoot.md): investigate Server, model, and connection issues.
diff --git a/docs/en/docs/get-started/meta.json b/docs/en/docs/get-started/meta.json
index 2eecee375d..443e11093d 100644
--- a/docs/en/docs/get-started/meta.json
+++ b/docs/en/docs/get-started/meta.json
@@ -2,6 +2,7 @@
   "title": "Get started",
   "pages": [
     "quickstart",
+    "manual-start",
     "install-and-run",
     "configure-server-environment",
     "configure-models",
diff --git a/docs/zh/docs/get-started/manual-start.md b/docs/zh/docs/get-started/manual-start.md
new file mode 100644
index 0000000000..9d762619b2
--- /dev/null
+++ b/docs/zh/docs/get-started/manual-start.md
@@ -0,0 +1,278 @@
+---
+title: 手动启动 PowerContext
+description: 不使用配置向导，手动配置并启动 PowerContext Server，连接 Codex 并验证 Memory。
+---
+
+# 手动启动 PowerContext
+
+本页介绍不使用 powercontext config init 配置向导时，如何手动配置和启动 PowerContext Server，并将 Codex 绑定到一个 Scope。
+
+本页适合希望了解每一步、排查配置问题，或需要自己控制 Server 地址、端口、Dashboard 和认证方式的用户。如果希望使用交互式配置向导快速完成安装，请看[快速开始](quickstart.md)。
+
+## 手动启动和快速启动的区别
+
+快速启动使用配置向导：
+
+~~~text
+config init → 生成 .env → 启动 Server → 创建 Scope → 连接 Agent
+~~~
+
+手动启动不运行 config init，而是自己准备环境变量或配置文件：
+
+~~~text
+手动写配置 → validate → server run → 检查 Server → 创建 Scope → 绑定 Agent
+~~~
+
+手动启动不是从源码编译 PowerContext，而是不依赖配置向导，自己决定 Server 的运行参数。
+
+## 前置条件
+
+需要 Python 3.11 或更高版本、Git、[uv](https://docs.astral.sh/uv/getting-started/installation/)，以及要连接的 Agent CLI（例如 Codex CLI）。
+
+~~~bash
+python3 --version
+git --version
+uv --version
+~~~
+
+## 1. 安装 PowerContext
+
+如果尚未安装 uv，可以先执行：
+
+~~~bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source "$HOME/.local/bin/env"
+~~~
+
+安装 PowerContext CLI 和本地 Server：
+
+~~~bash
+uv tool install --force "powercontext[cli,server]==1.3.0"
+powercontext --version
+powercontext --help
+~~~
+
+## 2. 停止可能正在运行的个人服务
+
+如果之前使用过 powercontext service install，系统中可能已有个人后台 Server。它可能占用默认端口，导致你误以为检查的是手动启动的 Server。
+
+~~~bash
+powercontext service status
+~~~
+
+如果个人服务正在运行，停止它：
+
+~~~bash
+powercontext service stop
+~~~
+
+这个命令会停止个人服务并禁止它自动启动，但会保留服务配置和数据。
+
+## 3. 创建手动配置文件
+
+~~~bash
+mkdir -p ~/powercontext-manual
+cd ~/powercontext-manual
+nano manual.env
+~~~
+
+在 manual.env 中写入：
+
+~~~dotenv
+POWERCONTEXT_SERVER_HTTP_HOST=127.0.0.1
+POWERCONTEXT_SERVER_HTTP_PORT=18080
+POWERCONTEXT_SERVER_DASHBOARD_ENABLED=true
+POWERCONTEXT_SERVER_ACCESS_MODE=disabled
+~~~
+
+配置项作用：
+
+| 配置项 | 作用 |
+| --- | --- |
+| POWERCONTEXT_SERVER_HTTP_HOST | 只监听本机地址 |
+| POWERCONTEXT_SERVER_HTTP_PORT | 监听 18080 端口 |
+| POWERCONTEXT_SERVER_DASHBOARD_ENABLED | 开启 Dashboard |
+| POWERCONTEXT_SERVER_ACCESS_MODE | 关闭本机测试所需的认证 |
+
+本配置没有指定数据库和模型，因此使用默认 SQLite，并且不启用模型推理能力。
+
+## 4. 验证手动配置
+
+~~~bash
+env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
+  powercontext config validate \
+  --env-file ~/powercontext-manual/manual.env
+~~~
+
+成功时会显示 Configuration is valid。这一步只验证配置，不会启动 Server。
+
+## 5. 手动启动 Server
+
+~~~bash
+env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
+  powercontext server run \
+  --env-file ~/powercontext-manual/manual.env
+~~~
+
+保持这个终端运行。成功启动时会看到类似日志：
+
+~~~text
+PowerContext Server is ready
+Uvicorn running on http://127.0.0.1:18080
+~~~
+
+按 Ctrl-C 可以停止前台 Server。没有配置 Generation 和 Embedding 模型时会出现提示，但不影响基础 Memory 的显式保存和召回。
+
+## 6. 访问 Dashboard
+
+在浏览器打开：
+
+~~~text
+http://127.0.0.1:18080/dashboard/home
+~~~
+
+认证已关闭，因此本机可以直接访问。第一次打开页面没有数据是正常的。
+
+## 7. 检查 Server
+
+保持 Server 运行，另开终端执行：
+
+~~~bash
+env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
+  POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \
+  powercontext doctor
+~~~
+
+继续检查：
+
+~~~bash
+env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
+  POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \
+  powercontext ready
+~~~
+
+~~~bash
+env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
+  POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \
+  powercontext capabilities
+~~~
+
+预期结果包括：
+
+~~~text
+server liveness: ok - http://127.0.0.1:18080
+server readiness: ok - http://127.0.0.1:18080
+access_mode: disabled
+database: ready
+~~~
+
+doctor 检查安装、Server 存活和就绪状态；ready 检查服务是否可以提供请求；capabilities 显示当前能力。
+
+## 8. 手动创建 Scope
+
+Scope 是项目上下文数据的隔离空间，用于隔离 Source、Memory、Topic Memory、Handoff 和 Agent 召回数据。
+
+使用 Python Client 手动调用 Server 创建 Scope。保持 Server 运行，在另一个终端执行：
+
+~~~bash
+cd ~/powercontext-manual
+POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \
+uv run --with "powercontext[client]==1.3.0" python - <<'PY'
+import asyncio
+import os
+from powercontext.client import PowerContextClient
+from powercontext.http import CreateScopeRequest
+
+async def main():
+    async with PowerContextClient(os.environ["POWERCONTEXT_CLIENT_SERVER_URL"]) as client:
+        scope = await client.create_scope(
+            CreateScopeRequest(
+                title="manual-powercontext-demo",
+                summary="Scope created during manual setup",
+                idempotency_key="manual-powercontext-demo-v1",
+            )
+        )
+        print("scope_id:", scope.scope_id)
+
+asyncio.run(main())
+PY
+~~~
+
+Server 会返回真实的 scope_id。后续绑定 Agent 时必须使用这个 ID，不能根据 Scope 标题自行拼接。
+
+## 9. 绑定 Codex Agent
+
+将真实 Scope ID 设置到当前终端：
+
+~~~bash
+export POWERCONTEXT_CODEX_SCOPE_ID=替换为Server返回的真实scope_id
+~~~
+
+安装与 Server 版本匹配的 Codex 插件，并指定手动启动的 Server：
+
+~~~bash
+powercontext setup codex \
+  --ref powercontext-v1.3.0 \
+  --server-url http://127.0.0.1:18080
+powercontext doctor codex
+~~~
+
+成功时应看到插件、MCP 和工具发现检查通过。安装插件不会启动 Server，因此 Server 终端必须保持运行。
+
+## 10. 验证显式 Memory 和跨会话召回
+
+从设置了 POWERCONTEXT_CODEX_SCOPE_ID 的终端启动新的 Codex：
+
+~~~bash
+codex
+~~~
+
+发送一条明确要求保存的消息：
+
+~~~text
+请把下面这条决定保存到 PowerContext：
+
+Aurora 项目使用 uv 管理 Python 依赖，配置文件使用 .env；第一阶段部署在 Linux 服务器上。
+~~~
+
+退出 Codex 后，在相同 Scope 下重新启动新会话，并询问：
+
+~~~text
+请从 PowerContext 找回 Aurora 项目的依赖管理和部署决定。
+~~~
+
+如果 Agent 找回相同内容，并显示 Memory 的 active 状态、来源和 revision，说明手动启动、Scope 绑定、显式保存和跨会话召回都验证成功。
+
+## 能力边界
+
+本页没有配置 Generation 和 Embedding 模型，因此可以验证显式 Memory、全文搜索和跨会话召回，但不能期待自动 Memory 提取、Topic Memory、Experience 或 Skill 自动生成。需要这些能力时，请参考[模型配置](configure-models.md)。
+
+## 常见问题
+
+### capabilities 显示 extraction disabled
+
+这是因为没有配置 Generation 和 Embedding 模型，不影响基础 Memory 的显式保存与召回。
+
+### capabilities 返回 401
+
+通常是 Server 开启了认证但客户端没有 Token。确认 manual.env 中的 POWERCONTEXT_SERVER_ACCESS_MODE=disabled，并使用 env -i 避免继承旧环境变量。
+
+### 检查到了 8000 而不是 18080
+
+检查时显式设置客户端地址：
+
+~~~bash
+POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 powercontext ready
+~~~
+
+### Dashboard 没有数据
+
+首次打开没有数据是正常的。需要先通过 Agent 或 API 写入 Source 或 Memory，并确认 Dashboard 和 Agent 使用同一个 Server 和 Scope。
+
+## 相关文档
+
+- [快速开始](quickstart.md)：使用配置向导完成完整记忆体验；
+- [配置 Server 环境](configure-server-environment.md)：了解配置文件和环境变量；
+- [配置模型](configure-models.md)：启用自动提取和向量检索；
+- [部署 Server](../operate/deploy-server.md)：运行个人后台服务和远程 Server；
+- [故障排查](../operate/troubleshoot.md)：排查 Server、模型和连接问题。
diff --git a/docs/zh/docs/get-started/meta.json b/docs/zh/docs/get-started/meta.json
index 029dbe2848..b597080721 100644
--- a/docs/zh/docs/get-started/meta.json
+++ b/docs/zh/docs/get-started/meta.json
@@ -2,6 +2,7 @@
   "title": "开始使用",
   "pages": [
     "quickstart",
+    "manual-start",
     "install-and-run",
     "configure-server-environment",
     "configure-models",

From 56167745b42e7d4b709e1fa9366feb0712bbacf8 Mon Sep 17 00:00:00 2001
From: CX33071 <3541053286@qq.com>
Date: Sat, 17 Oct 2026 20:23:30 +0800
Subject: [PATCH 2/4] docs:add Japanese manual startup guides

---
 README_JP.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/README_JP.md b/README_JP.md
index 4952d99ab4..7274f27ac5 100644
--- a/README_JP.md
+++ b/README_JP.md
@@ -1,5 +1,4 @@
 # PowerContext
-
 **作業とともに残るコンテキスト —— セッション、Agent、人をまたいで。**
 
 [![PyPI version](https://img.shields.io/pypi/v/powercontext)](https://pypi.org/project/powercontext/)
@@ -9,7 +8,7 @@
 
 *[English](README.md) · [中文](README_CN.md) · [日本語](README_JP.md)*
 
-[Web サイト](https://powercontext.oceanbase.io/en/) · [クイックスタート](https://powercontext.oceanbase.io/en/docs/get-started/quickstart/) · [Agent 連携](https://powercontext.oceanbase.io/en/docs/integrations/) · [ベンチマーク](https://powercontext.oceanbase.io/en/benchmarks/) · [インターフェース](https://powercontext.oceanbase.io/en/docs/develop/interfaces/)
+[Web サイト](https://powercontext.oceanbase.io/en/) · [クイックスタート](https://powercontext.oceanbase.io/en/docs/get-started/quickstart/) · [手動起動](docs/en/docs/get-started/manual-start.md) · [Agent 連携](https://powercontext.oceanbase.io/en/docs/integrations/) · [ベンチマーク](https://powercontext.oceanbase.io/en/benchmarks/) · [インターフェース](https://powercontext.oceanbase.io/en/docs/develop/interfaces/)
 
 ## クイックスタート
 
@@ -29,6 +28,8 @@ PowerContext 1.3.0 には対話式セットアップウィザードが含まれ
 | Source を自動処理し、Topic Memory やセマンティック検索を使う | **Full memory** | Generation と Embedding API の個別の認証情報。スケジュールと Scope ポリシーも適用されます |
 | Python で基本ワークフローを学ぶ | 最初の 7 本の Jupyter チュートリアル | リポジトリの checkout と `uv`。モデルや API キーは不要 |
 
+手動で PowerContext を設定して起動したい場合は、[手動起動ガイド](docs/en/docs/get-started/manual-start.md)を参照してください。
+
 ### 1. ウィザードをインストールして実行する
 
 ```bash

From faf92653d2dd618834552386ae8605aa2dadc9a6 Mon Sep 17 00:00:00 2001
From: CX33071 <3541053286@qq.com>
Date: Sat, 17 Oct 2026 20:39:33 +0800
Subject: [PATCH 3/4] docs:clarify manual startup platform support

---
 docs/en/docs/get-started/manual-start.md | 2 ++
 docs/zh/docs/get-started/manual-start.md | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/docs/en/docs/get-started/manual-start.md b/docs/en/docs/get-started/manual-start.md
index ad93958b30..54311bbf36 100644
--- a/docs/en/docs/get-started/manual-start.md
+++ b/docs/en/docs/get-started/manual-start.md
@@ -7,6 +7,8 @@ description: Configure and start the PowerContext Server manually without the se
 
 This page explains how to configure and start the PowerContext Server without using the powercontext config init setup wizard, then bind Codex to a Scope.
 
+This guide applies to macOS and Linux only. It uses POSIX shell syntax such as `source`, `env -i`, and here-documents; Windows PowerShell is not covered by this guide.
+
 Use this page if you want to understand each step, troubleshoot configuration, or control the Server address, port, Dashboard, and authentication yourself. If you prefer the interactive setup wizard, see [Quick Start](quickstart.md).
 
 ## Manual startup versus Quick Start
diff --git a/docs/zh/docs/get-started/manual-start.md b/docs/zh/docs/get-started/manual-start.md
index 9d762619b2..f59856a7fe 100644
--- a/docs/zh/docs/get-started/manual-start.md
+++ b/docs/zh/docs/get-started/manual-start.md
@@ -7,6 +7,8 @@ description: 不使用配置向导，手动配置并启动 PowerContext Server
 
 本页介绍不使用 powercontext config init 配置向导时，如何手动配置和启动 PowerContext Server，并将 Codex 绑定到一个 Scope。
 
+本指南仅适用于 macOS 和 Linux。文中的命令使用 POSIX Shell 语法，例如 `source`、`env -i` 和 here-document；本文不提供 Windows PowerShell 流程。
+
 本页适合希望了解每一步、排查配置问题，或需要自己控制 Server 地址、端口、Dashboard 和认证方式的用户。如果希望使用交互式配置向导快速完成安装，请看[快速开始](quickstart.md)。
 
 ## 手动启动和快速启动的区别

From cd6859805a5109ac3d93a35b6cfdd2b02f0476ce Mon Sep 17 00:00:00 2001
From: CX33071 <3541053286@qq.com>
Date: Sat, 17 Oct 2026 21:13:14 +0800
Subject: [PATCH 4/4] docs:use standard Markdown code fences

---
 docs/en/docs/get-started/manual-start.md | 96 ++++++++++++------------
 docs/zh/docs/get-started/manual-start.md | 96 ++++++++++++------------
 2 files changed, 96 insertions(+), 96 deletions(-)

diff --git a/docs/en/docs/get-started/manual-start.md b/docs/en/docs/get-started/manual-start.md
index 54311bbf36..435f93385a 100644
--- a/docs/en/docs/get-started/manual-start.md
+++ b/docs/en/docs/get-started/manual-start.md
@@ -15,15 +15,15 @@ Use this page if you want to understand each step, troubleshoot configuration, o
 
 Quick Start uses the setup wizard:
 
-~~~text
+```text
 config init → generate .env → start Server → create Scope → connect Agent
-~~~
+```
 
 Manual startup does not run config init. You prepare the environment variables or configuration file yourself:
 
-~~~text
+```text
 write configuration → validate → server run → check Server → create Scope → bind Agent
-~~~
+```
 
 Manual startup does not mean compiling PowerContext from source. It means running PowerContext without relying on the configuration wizard and choosing the Server settings yourself.
 
@@ -31,61 +31,61 @@ Manual startup does not mean compiling PowerContext from source. It means runnin
 
 You need Python 3.11 or newer, Git, [uv](https://docs.astral.sh/uv/getting-started/installation/), and an Agent CLI such as Codex CLI if you want to connect an Agent.
 
-~~~bash
+```bash
 python3 --version
 git --version
 uv --version
-~~~
+```
 
 ## 1. Install PowerContext
 
 If uv is not installed, run:
 
-~~~bash
+```bash
 curl -LsSf https://astral.sh/uv/install.sh | sh
 source "$HOME/.local/bin/env"
-~~~
+```
 
 Install the PowerContext CLI and local Server:
 
-~~~bash
+```bash
 uv tool install --force "powercontext[cli,server]==1.3.0"
 powercontext --version
 powercontext --help
-~~~
+```
 
 ## 2. Stop a possibly running personal service
 
 If you previously ran powercontext service install, a personal background Server may already be running. It may occupy the default port and make it unclear which Server you are checking.
 
-~~~bash
+```bash
 powercontext service status
-~~~
+```
 
 If the personal service is running, stop it:
 
-~~~bash
+```bash
 powercontext service stop
-~~~
+```
 
 This stops the personal service and prevents automatic activation while keeping its configuration and data.
 
 ## 3. Create a manual configuration file
 
-~~~bash
+```bash
 mkdir -p ~/powercontext-manual
 cd ~/powercontext-manual
 nano manual.env
-~~~
+```
 
 Put the following values in manual.env:
 
-~~~dotenv
+```dotenv
 POWERCONTEXT_SERVER_HTTP_HOST=127.0.0.1
 POWERCONTEXT_SERVER_HTTP_PORT=18080
 POWERCONTEXT_SERVER_DASHBOARD_ENABLED=true
 POWERCONTEXT_SERVER_ACCESS_MODE=disabled
-~~~
+```
 
 The settings mean:
 
@@ -100,28 +100,28 @@ This configuration does not specify a database or models, so it uses the default
 
 ## 4. Validate the manual configuration
 
-~~~bash
+```bash
 env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
   powercontext config validate \
   --env-file ~/powercontext-manual/manual.env
-~~~
+```
 
 A successful command prints Configuration is valid. This step only validates the configuration; it does not start the Server.
 
 ## 5. Start the Server manually
 
-~~~bash
+```bash
 env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
   powercontext server run \
   --env-file ~/powercontext-manual/manual.env
-~~~
+```
 
 Keep this terminal open. A successful startup looks similar to:
 
-~~~text
+```text
 PowerContext Server is ready
 Uvicorn running on http://127.0.0.1:18080
-~~~
+```
 
 Press Ctrl-C to stop the foreground Server. If Generation and Embedding models are not configured, PowerContext prints a notice, but explicit Basic Memory saves and recall still work.
 
@@ -129,9 +129,9 @@ Press Ctrl-C to stop the foreground Server. If Generation and Embedding models a
 
 Open the following address in a browser:
 
-~~~text
+```text
 http://127.0.0.1:18080/dashboard/home
-~~~
+```
 
 Authentication is disabled, so the page can be opened directly from the local machine. An empty Dashboard on the first visit is expected.
 
@@ -139,34 +139,34 @@ Authentication is disabled, so the page can be opened directly from the local ma
 
 Keep the Server running and open another terminal:
 
-~~~bash
+```bash
 env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
   POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \
   powercontext doctor
-~~~
+```
 
 Continue with:
 
-~~~bash
+```bash
 env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
   POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \
   powercontext ready
-~~~
+```
 
-~~~bash
+```bash
 env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
   POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \
   powercontext capabilities
-~~~
+```
 
 Expected output includes:
 
-~~~text
+```text
 server liveness: ok - http://127.0.0.1:18080
 server readiness: ok - http://127.0.0.1:18080
 access_mode: disabled
 database: ready
-~~~
+```
 
 doctor checks the installation, Server liveness, and readiness. ready checks whether the Server can provide requests. capabilities shows the currently enabled capabilities.
 
@@ -176,7 +176,7 @@ A Scope is an isolated space for project context. It separates Sources, Memory,
 
 Use the Python Client to call the Server and create a Scope manually. Keep the Server running and execute the following in another terminal:
 
-~~~bash
+```bash
 cd ~/powercontext-manual
 POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \
 uv run --with "powercontext[client]==1.3.0" python - <<'PY'
@@ -198,7 +198,7 @@ async def main():
 
 asyncio.run(main())
 PY
-~~~
+```
 
 The Server returns the real scope_id. Use this ID when binding the Agent; do not construct an ID from the Scope title.
 
@@ -206,18 +206,18 @@ The Server returns the real scope_id. Use this ID when binding the Agent; do not
 
 Set the real Scope ID in the current terminal:
 
-~~~bash
+```bash
 export POWERCONTEXT_CODEX_SCOPE_ID=replace-with-the-scope-id-returned-by-the-server
-~~~
+```
 
 Install the Codex plugin matching the Server version and point it to the manually started Server:
 
-~~~bash
+```bash
 powercontext setup codex \
   --ref powercontext-v1.3.0 \
   --server-url http://127.0.0.1:18080
 powercontext doctor codex
-~~~
+```
 
 The checks should confirm that the plugin, MCP, and tool discovery are working. Installing the plugin does not start the Server, so the Server terminal must remain open.
 
@@ -225,23 +225,23 @@ The checks should confirm that the plugin, MCP, and tool discovery are working.
 
 Start a new Codex session from a terminal where POWERCONTEXT_CODEX_SCOPE_ID is set:
 
-~~~bash
+```bash
 codex
-~~~
+```
 
 Send a message that explicitly asks Codex to save a decision:
 
-~~~text
+```text
 Please save the following decision to PowerContext:
 
 The Aurora project uses uv to manage Python dependencies and .env for configuration. The first phase will be deployed on a Linux server.
-~~~
+```
 
 Exit Codex, start a new session with the same Scope, and ask:
 
-~~~text
+```text
 Please retrieve the Aurora project's dependency management and deployment decision from PowerContext.
-~~~
+```
 
 If the Agent retrieves the same content and shows the Memory as active with its source and revision, manual startup, Scope binding, explicit saving, and cross-session recall have all been verified.
 
@@ -263,9 +263,9 @@ The Server is usually enforcing authentication while the client has no Token. Co
 
 Set the client address explicitly:
 
-~~~bash
+```bash
 POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 powercontext ready
-~~~
+```
 
 ### The Dashboard has no data
 
diff --git a/docs/zh/docs/get-started/manual-start.md b/docs/zh/docs/get-started/manual-start.md
index f59856a7fe..1f8cd96f42 100644
--- a/docs/zh/docs/get-started/manual-start.md
+++ b/docs/zh/docs/get-started/manual-start.md
@@ -15,15 +15,15 @@ description: 不使用配置向导，手动配置并启动 PowerContext Server
 
 快速启动使用配置向导：
 
-~~~text
+```text
 config init → 生成 .env → 启动 Server → 创建 Scope → 连接 Agent
-~~~
+```
 
 手动启动不运行 config init，而是自己准备环境变量或配置文件：
 
-~~~text
+```text
 手动写配置 → validate → server run → 检查 Server → 创建 Scope → 绑定 Agent
-~~~
+```
 
 手动启动不是从源码编译 PowerContext，而是不依赖配置向导，自己决定 Server 的运行参数。
 
@@ -31,61 +31,61 @@ config init → 生成 .env → 启动 Server → 创建 Scope → 连接 Agent
 
 需要 Python 3.11 或更高版本、Git、[uv](https://docs.astral.sh/uv/getting-started/installation/)，以及要连接的 Agent CLI（例如 Codex CLI）。
 
-~~~bash
+```bash
 python3 --version
 git --version
 uv --version
-~~~
+```
 
 ## 1. 安装 PowerContext
 
 如果尚未安装 uv，可以先执行：
 
-~~~bash
+```bash
 curl -LsSf https://astral.sh/uv/install.sh | sh
 source "$HOME/.local/bin/env"
-~~~
+```
 
 安装 PowerContext CLI 和本地 Server：
 
-~~~bash
+```bash
 uv tool install --force "powercontext[cli,server]==1.3.0"
 powercontext --version
 powercontext --help
-~~~
+```
 
 ## 2. 停止可能正在运行的个人服务
 
 如果之前使用过 powercontext service install，系统中可能已有个人后台 Server。它可能占用默认端口，导致你误以为检查的是手动启动的 Server。
 
-~~~bash
+```bash
 powercontext service status
-~~~
+```
 
 如果个人服务正在运行，停止它：
 
-~~~bash
+```bash
 powercontext service stop
-~~~
+```
 
 这个命令会停止个人服务并禁止它自动启动，但会保留服务配置和数据。
 
 ## 3. 创建手动配置文件
 
-~~~bash
+```bash
 mkdir -p ~/powercontext-manual
 cd ~/powercontext-manual
 nano manual.env
-~~~
+```
 
 在 manual.env 中写入：
 
-~~~dotenv
+```dotenv
 POWERCONTEXT_SERVER_HTTP_HOST=127.0.0.1
 POWERCONTEXT_SERVER_HTTP_PORT=18080
 POWERCONTEXT_SERVER_DASHBOARD_ENABLED=true
 POWERCONTEXT_SERVER_ACCESS_MODE=disabled
-~~~
+```
 
 配置项作用：
 
@@ -100,28 +100,28 @@ POWERCONTEXT_SERVER_ACCESS_MODE=disabled
 
 ## 4. 验证手动配置
 
-~~~bash
+```bash
 env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
   powercontext config validate \
   --env-file ~/powercontext-manual/manual.env
-~~~
+```
 
 成功时会显示 Configuration is valid。这一步只验证配置，不会启动 Server。
 
 ## 5. 手动启动 Server
 
-~~~bash
+```bash
 env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
   powercontext server run \
   --env-file ~/powercontext-manual/manual.env
-~~~
+```
 
 保持这个终端运行。成功启动时会看到类似日志：
 
-~~~text
+```text
 PowerContext Server is ready
 Uvicorn running on http://127.0.0.1:18080
-~~~
+```
 
 按 Ctrl-C 可以停止前台 Server。没有配置 Generation 和 Embedding 模型时会出现提示，但不影响基础 Memory 的显式保存和召回。
 
@@ -129,9 +129,9 @@ Uvicorn running on http://127.0.0.1:18080
 
 在浏览器打开：
 
-~~~text
+```text
 http://127.0.0.1:18080/dashboard/home
-~~~
+```
 
 认证已关闭，因此本机可以直接访问。第一次打开页面没有数据是正常的。
 
@@ -139,34 +139,34 @@ http://127.0.0.1:18080/dashboard/home
 
 保持 Server 运行，另开终端执行：
 
-~~~bash
+```bash
 env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
   POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \
   powercontext doctor
-~~~
+```
 
 继续检查：
 
-~~~bash
+```bash
 env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
   POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \
   powercontext ready
-~~~
+```
 
-~~~bash
+```bash
 env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \
   POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \
   powercontext capabilities
-~~~
+```
 
 预期结果包括：
 
-~~~text
+```text
 server liveness: ok - http://127.0.0.1:18080
 server readiness: ok - http://127.0.0.1:18080
 access_mode: disabled
 database: ready
-~~~
+```
 
 doctor 检查安装、Server 存活和就绪状态；ready 检查服务是否可以提供请求；capabilities 显示当前能力。
 
@@ -176,7 +176,7 @@ Scope 是项目上下文数据的隔离空间，用于隔离 Source、Memory、T
 
 使用 Python Client 手动调用 Server 创建 Scope。保持 Server 运行，在另一个终端执行：
 
-~~~bash
+```bash
 cd ~/powercontext-manual
 POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \
 uv run --with "powercontext[client]==1.3.0" python - <<'PY'
@@ -198,7 +198,7 @@ async def main():
 
 asyncio.run(main())
 PY
-~~~
+```
 
 Server 会返回真实的 scope_id。后续绑定 Agent 时必须使用这个 ID，不能根据 Scope 标题自行拼接。
 
@@ -206,18 +206,18 @@ Server 会返回真实的 scope_id。后续绑定 Agent 时必须使用这个 ID
 
 将真实 Scope ID 设置到当前终端：
 
-~~~bash
+```bash
 export POWERCONTEXT_CODEX_SCOPE_ID=替换为Server返回的真实scope_id
-~~~
+```
 
 安装与 Server 版本匹配的 Codex 插件，并指定手动启动的 Server：
 
-~~~bash
+```bash
 powercontext setup codex \
   --ref powercontext-v1.3.0 \
   --server-url http://127.0.0.1:18080
 powercontext doctor codex
-~~~
+```
 
 成功时应看到插件、MCP 和工具发现检查通过。安装插件不会启动 Server，因此 Server 终端必须保持运行。
 
@@ -225,23 +225,23 @@ powercontext doctor codex
 
 从设置了 POWERCONTEXT_CODEX_SCOPE_ID 的终端启动新的 Codex：
 
-~~~bash
+```bash
 codex
-~~~
+```
 
 发送一条明确要求保存的消息：
 
-~~~text
+```text
 请把下面这条决定保存到 PowerContext：
 
 Aurora 项目使用 uv 管理 Python 依赖，配置文件使用 .env；第一阶段部署在 Linux 服务器上。
-~~~
+```
 
 退出 Codex 后，在相同 Scope 下重新启动新会话，并询问：
 
-~~~text
+```text
 请从 PowerContext 找回 Aurora 项目的依赖管理和部署决定。
-~~~
+```
 
 如果 Agent 找回相同内容，并显示 Memory 的 active 状态、来源和 revision，说明手动启动、Scope 绑定、显式保存和跨会话召回都验证成功。
 
@@ -263,9 +263,9 @@ Aurora 项目使用 uv 管理 Python 依赖，配置文件使用 .env；第一
 
 检查时显式设置客户端地址：
 
-~~~bash
+```bash
 POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 powercontext ready
-~~~
+```
 
 ### Dashboard 没有数据