Teingi · Teingi · Aug 31, 2026 · Aug 31, 2026 · Aug 31, 2026 · Aug 31, 2026
diff --git a/README.md b/README.md
@@ -22,15 +22,23 @@ collaboration. It turns shared work into project context that can be understood,
 
 ## Quick start
 
-You need macOS or Linux, Python 3.11 or newer, [`uv`](https://docs.astral.sh/uv/), and at least one supported agent
-host.
+You need macOS or Linux, Python 3.11 or newer, and [`uv`](https://docs.astral.sh/uv/). Choose your entry:
 
-### 1. Install PowerContext and integrations
+- already have an AI application and do not use an Agent Host: follow the
+  [HTTP API lifecycle tutorial](docs/en/docs/tutorials/api-quickstart.md) to complete the first Source, Memory,
+  PreparedContext, Experience, Skill, and Review loop over HTTP;
+- use Codex, Claude Code, DSH, OpenCode, or another Host: follow the
+  [Agent step-by-step quickstart](docs/en/docs/tutorials/agent-quickstart.md) for its actual Memory, automatic-recall,
+  and Handoff surface.
+
+The commands below are the shorter shared installation path.
+
+### 1. Install PowerContext, then add integrations for Agent Hosts
 
 ```bash
 uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
 
-# Choose one or more integrations. Every setup command installs from the master branch.
+# Only the Agent Host path needs one or more integrations. Every setup command installs from master.
 powercontext setup codex --source oceanbase/powercontext --ref master
 powercontext setup claude-code --source oceanbase/powercontext --ref master
 powercontext setup dsh --source oceanbase/powercontext --ref master
@@ -47,7 +55,7 @@ powercontext setup select --host codex --host claude-code --host opencode \
 
 The first command installs the CLI and local Server from the latest `master` revision in an isolated environment.
 Every setup command installs its integration from the same `master` revision. Run setup again to refresh an existing
-integration.
+integration. HTTP API users need only the first install command and can skip every `powercontext setup` command.
 
 ### 2. Start and verify the local Server
 
@@ -68,6 +76,28 @@ powercontext doctor codex  # Replace codex with the host you installed.
 By default, the Server listens on `127.0.0.1:8000`, exposes Streamable HTTP MCP at `/mcp`, and persists data in a
 local SQLite database. Explicit Memory operations work without configuring an inference provider.
 
+### 3. Complete the Agent Memory and Handoff loop
+
+Start a new session from one project directory and follow the prompts in the
+[Agent step-by-step quickstart](docs/en/docs/tutorials/agent-quickstart.md). It shows how to:
+
+1. select and diagnose an installed Agent Host;
+2. save explicit project Memory and recover it in another session;
+3. use one-line, `pc_*`, or `/pc` Handoff according to the Host's real capabilities;
+4. verify a non-Codex DSH-to-OpenCode continuation with one exact Revision.
+
+No generation model is required for this first loop. Configure inference only when you continue to model-backed
+extraction and vector search. For the Codex-specific Hook and one-line flow, continue with the
+[complete Codex tutorial](docs/en/docs/tutorials/codex-quickstart.md).
+
+### 4. Or add the HTTP API to your own AI
+
+Without an Agent Host, call `POST /v1/context/prepare` before each model request and supply the returned read-only,
+untrusted historical context to the model. Call `POST /v1/memory/remember` only after explicit user or business-policy
+authorization. The [HTTP API lifecycle tutorial](docs/en/docs/tutorials/api-quickstart.md) provides one small Python
+learning path; use the [Scalar API Reference](https://oceanbase.github.io/powercontext/api/) for every endpoint and
+schema.
+
 ## Core capabilities
 
 | Capability | Core value |

diff --git a/README_CN.md b/README_CN.md
@@ -21,14 +21,21 @@ PowerContext 是 [PowerMem](https://www.powermem.ai/) 的升级版本，也是
 
 ## 快速开始
 
-你需要 macOS 或 Linux、Python 3.11 或更高版本、[`uv`](https://docs.astral.sh/uv/)，以及至少一个支持的 Agent Host。
+你需要 macOS 或 Linux、Python 3.11 或更高版本，以及 [`uv`](https://docs.astral.sh/uv/)。先选择入口：
 
-### 1. 安装 PowerContext 和集成
+- 已经有自己的 AI 应用，不使用 Agent Host：跟着 [HTTP API 生命周期教程](docs/zh/docs/tutorials/api-quickstart.md)，
+  通过 HTTP 跑通第一个 Source、Memory、PreparedContext、Experience、Skill 和 Review 闭环；
+- 使用 Codex、Claude Code、DSH、OpenCode 等 Host：跟着
+  [Agent 分步入门](docs/zh/docs/tutorials/agent-quickstart.md)，按 Host 的真实能力接入 Memory、自动恢复和 Handoff。
+
+下面保留更短的公共安装路径。
+
+### 1. 安装 PowerContext；Agent 用户再安装集成
 
 ```bash
 uv tool install --force "powercontext[cli,server] @ git+https://github.com/oceanbase/powercontext.git@master"
 
-# 选择一个或多个集成。所有 setup 命令都从 master 分支安装。
+# 只有 Agent Host 路线需要选择一个或多个集成。所有 setup 命令都从 master 分支安装。
 powercontext setup codex --source oceanbase/powercontext --ref master
 powercontext setup claude-code --source oceanbase/powercontext --ref master
 powercontext setup dsh --source oceanbase/powercontext --ref master
@@ -44,7 +51,8 @@ powercontext setup select --host codex --host claude-code --host opencode \
 ```
 
 第一条命令会在隔离环境中从最新 `master` revision 安装 CLI 和本地 Server；每条 setup 命令都会从同一个
-`master` revision 安装对应集成。如需刷新现有集成，请再次运行 setup。
+`master` revision 安装对应集成。如需刷新现有集成，请再次运行 setup。HTTP API 用户只需第一条安装命令，可以
+跳过所有 `powercontext setup` 命令。
 
 ### 2. 启动并验证本地 Server
 
@@ -65,6 +73,26 @@ powercontext doctor codex  # 请把 codex 换成已安装的宿主。
 默认情况下，Server 监听 `127.0.0.1:8000`，在 `/mcp` 提供 Streamable HTTP MCP，并将数据持久化到本地
 SQLite 数据库。显式 Memory 操作无需配置 inference provider 即可使用。
 
+### 3. 跑通 Agent Memory 与 Handoff 闭环
+
+从一个项目目录开启新会话，并按照 [Agent 分步入门](docs/zh/docs/tutorials/agent-quickstart.md)中的提示词操作。
+教程会带你完成：
+
+1. 选择并诊断一个已经安装的 Agent Host；
+2. 保存显式项目 Memory，并在另一个会话中恢复；
+3. 按 Host 使用一句话、`pc_*` 或 `/pc` Handoff；
+4. 用 DSH → OpenCode 验证不依赖 Codex 的 exact Revision continuation。
+
+第一个闭环不需要 generation model。需要从 Source 自动抽取 Memory 或使用向量搜索时，再继续配置推理服务。
+Codex 专属 Hook 和一句话流程见 [Codex 完整教程](docs/zh/docs/tutorials/codex-quickstart.md)。
+
+### 4. 或者，为自己的 AI 接入 HTTP API
+
+不使用 Agent Host 时，在每次模型请求前调用 `POST /v1/context/prepare`，把返回的只读、不可信历史上下文交给
+模型；只有在用户或业务策略明确授权后，才调用 `POST /v1/memory/remember` 保存长期 Memory。
+[HTTP API 生命周期教程](docs/zh/docs/tutorials/api-quickstart.md)提供一个小型 Python 学习路径；全部 endpoint 和
+schema 请查 [Scalar API 参考](https://oceanbase.github.io/powercontext/api/)。
+
 ## 核心能力
 
 | 能力 | 核心价值 |

diff --git a/docs/en/docs/how-to/install-and-run.md b/docs/en/docs/how-to/install-and-run.md
@@ -5,6 +5,10 @@ description: Install PowerContext from Git and run the local Server.
 
 # Install and run
 
+If you are new to PowerContext, follow the [Agent step-by-step quickstart](../tutorials/agent-quickstart.md) to choose
+a host and complete Memory plus its supported Handoff path from zero. This guide focuses on installation roles,
+Server startup, seekDB, diagnostics, and updates for readers who already know which operation they need.
+
 ## Install the application
 
 You need Python 3.11 or newer, Git, and [`uv`](https://docs.astral.sh/uv/) on macOS or Linux. Then install

diff --git a/docs/en/docs/index.md b/docs/en/docs/index.md
@@ -1,20 +1,32 @@
 ---
 template: docs-overview.html
-title: Start with one project
-description: Install PowerContext, verify context across sessions, and choose the next task.
+title: Choose an Agent or API and complete the first loop
+description: Add the HTTP Memory API to an existing AI application, or configure an Agent and verify Memory and Handoff.
 page_type: docs-overview
 overview:
-  intro: Complete one cross-session loop first. Use the documentation navigation for setup, reference, and development details.
+  intro: If you are new to PowerContext, choose the entry that matches your application. Use HTTP directly from an existing AI application, or start with the Agent quickstart for Codex, Claude Code, OpenCode, and other hosts.
   sections:
-    - title: Continue the project
-      description: Save one decision, recover it in another session, or hand off current work.
+    - title: Recommended learning path
+      description: Complete a local API or Agent loop first, then connect another host or adopt the complete work workflow.
       cards:
-        - title: Codex quickstart
-          description: Install the local Server, save one project decision, and recover it in a new session.
+        - title: HTTP API lifecycle tutorial
+          description: Use one small Python flow to connect context, Experience, Skill, and Review; use Scalar for endpoint reference.
+          href: en/docs/tutorials/api-quickstart/
+        - title: Agent step-by-step quickstart
+          description: Choose a host, install and diagnose it, complete Memory, then use its one-line, pc_*, or /pc Handoff path.
+          href: en/docs/tutorials/agent-quickstart/
+        - title: Complete Codex tutorial
+          description: Go deeper into the Codex Hook, MCP Skill, Memory lifecycle, and one-line durable Handoff.
           href: en/docs/tutorials/codex-quickstart/
+        - title: Hand off current work
+          description: Use Work Contract, Handoff, Acknowledgement, and Task Outcome for the complete task loop.
+          href: en/docs/how-to/handoff-with-codex/
         - title: Continue in Claude Code
           description: Open the same project Memory from Claude Code and Codex.
           href: en/docs/how-to/configure-claude-code/
+        - title: Use DeepSeek Harness
+          description: Prepare context before each model step and use pc_* Memory and Handoff tools.
+          href: en/docs/how-to/configure-dsh/
         - title: Continue in Pi
           description: Open project context in Pi with the native package.
           href: en/docs/how-to/configure-pi/
@@ -24,12 +36,15 @@ overview:
         - title: Continue in OpenCode
           description: Recall and maintain project context with the native OpenCode plugin.
           href: en/docs/how-to/configure-opencode/
+        - title: Continue in Hermes
+          description: Use the MemoryProvider, /pc companion, and Handoff lifecycle operations.
+          href: en/docs/how-to/configure-hermes/
+        - title: Continue in WorkBuddy
+          description: Use the Prompt Hook, MCP Memory, and one-line durable Handoff.
+          href: en/docs/how-to/configure-workbuddy/
         - title: Load an Agent Plugin
           description: Use reusable PowerContext skills and MCP configuration in compatible agents.
           href: en/docs/how-to/configure-agent-plugin/
-        - title: Hand off current work
-          description: Prepare a checked Handoff for another task, session, or model.
-          href: en/docs/how-to/handoff-with-codex/
     - title: Understand and operate
       description: Decide what persists, configure the Server, or resolve a broken setup.
       cards:
@@ -52,7 +67,7 @@ overview:
           description: Run a persistent Server with health checks, authentication, and a safe network boundary.
           href: en/docs/how-to/deploy-server/
         - title: HTTP API
-          description: Call the Server from any language and find the complete OpenAPI contract.
+          description: Look up every Server path, error semantic, and the complete OpenAPI contract.
           href: en/docs/reference/http-api/
         - title: Review Candidates
           description: Inspect, revise, approve, or reject pending Experience and Skill proposals.

diff --git a/docs/en/docs/reference/http-api.md b/docs/en/docs/reference/http-api.md
@@ -8,6 +8,10 @@ description: Call the PowerContext Server over HTTP and find the complete OpenAP
 The HTTP API is the language-neutral interface to a running PowerContext Server. The default base URL is
 `http://127.0.0.1:8000`.
 
+If you are integrating PowerContext into your own AI application rather than looking up one field, start with the
+[HTTP API lifecycle tutorial](../tutorials/api-quickstart.md). This page remains the path, contract, and
+error-semantics reference.
+
 ## Discover the contract
 
 With a local unauthenticated Server running, open: