docs: consolidate Codex onboarding (oceanbase#1251)

Author: chenncy

README.md

@@ -8,47 +8,16 @@
 
 PowerContext gives agents durable, project-scoped context. A later session can recover a decision, outcome, current state, or next step without relying on chat history. PowerContext includes a local Server, SQLite storage, an async Python client, a Core SDK, a CLI, a Codex plugin, and a DeepSeek Harness plugin.
 
+## Get started
 
-## Install for Codex or DeepSeek Harness
+Use [Install and run](docs/en/docs/how-to/install-and-run.md) for prerequisites, installation, Server startup, and
+verification. Then choose a host integration:
 
-Prerequisites:
+- [Codex quickstart](docs/en/docs/tutorials/codex-quickstart.md) provides a first cross-session Memory workflow.
+- [Configure Codex](docs/en/docs/how-to/configure-codex.md) and
+  [Configure DeepSeek Harness](docs/en/docs/how-to/configure-dsh.md) cover host-specific setup.
 
-- macOS or Linux;
-- [uv](https://docs.astral.sh/uv/getting-started/installation/);
-- Codex CLI and/or DeepSeek Harness (`dsh`).
-
-```bash
-uv tool install "powercontext[cli,server]==0.0.1"
-powercontext --version
-```
-
-The version command should print `0.0.1`. Configure the matching host plugin from the same release tag:
-
-```bash
-powercontext setup codex --source oceanbase/powercontext --ref v0.0.1
-powercontext setup dsh --source oceanbase/powercontext --ref v0.0.1
-```
-
-Start the local service in a terminal:
-
-```bash
-powercontext server run
-```
-
-The Server listens on `http://127.0.0.1:8000` by default and stores its SQLite database in the platform-specific user data directory. Keep this process running while using PowerContext. In another terminal, verify the package, Server,
-and Codex integration:
-
-```bash
-powercontext doctor
-powercontext doctor codex
-powercontext doctor dsh
-```
-
-Runtime or database failures make the Server not ready. A configured inference failure is reported as degraded without removing the Server from traffic; the separate Codex and DeepSeek Harness commands do not affect Server health.
-
-Start a new Codex session after setup. Open `/hooks` once and approve the PowerContext hook if Codex asks for trust.
-
-See the [Codex quickstart](docs/en/docs/tutorials/codex-quickstart.md) for a first cross-session workflow.
+For other tasks, start from the [documentation overview](docs/en/docs/index.md).
 
 ## Choose an interface
 

docs/en/docs/explanation/memory-and-handoff.md

@@ -0,0 +1,40 @@
+---
+title: Understand Memory and Handoff
+description: Learn the different purposes and boundaries of durable project Memory and a temporary work Handoff.
+---
+
+# Understand Memory and Handoff
+
+PowerContext provides both durable project Memory and a temporary Handoff. Both help later work continue, but they
+solve different problems.
+
+## Memory: durable project knowledge
+
+Memory stores information that later work may need and can understand independently, such as a decision, constraint,
+current state, or next step. It belongs to a project scope, can be searched, and can be revised or retired. Revision
+and retirement preserve history rather than silently overwriting an earlier record.
+
+Codex should write Memory only when the user explicitly asks to save it. The prompt Hook captures prompts as Source
+evidence, but capture is not the same as automatically creating Memory. It should not create an extra Memory merely to
+duplicate the current prompt.
+
+## Handoff: temporary transfer of work
+
+A Handoff organizes a task's current objective, verified progress, blockers, next action, and evidence into temporary
+content for a receiver. It must be explicitly prepared, inspected, and finalized. The receiver gets the complete
+Prepared Handoff and checks it against current code and instructions.
+
+Drafts and Prepared Handoffs are not durable project knowledge by default. Commit a Handoff only when the user
+explicitly asks to retain a milestone.
+
+## Choose the right one
+
+| Your need | Use |
+| --- | --- |
+| A later project task needs a decision, constraint, or next step | Memory |
+| Transfer the complete current task to another task, session, or model | Handoff |
+| Record the current user prompt as processing evidence | Let the prompt Hook capture a Source |
+| Retain a verified Handoff milestone for long-term reuse | Commit the Handoff on user request, or save it as Memory |
+
+Never store secrets, access tokens, or other sensitive information in either. For the Handoff procedure, see
+[Hand off work in Codex](../how-to/handoff-with-codex.md).

docs/en/docs/how-to/configure-codex.md

@@ -19,13 +19,13 @@ directory. It is safe to run again. Pass the same `--ref` used to install the Po
 Open a new Codex session after setup. Use `/hooks` to inspect and, when prompted, trust the PowerContext
 `UserPromptSubmit` hook.
 
-## Understand what the plugin does
+## Understand automatic recall, Memory, and Handoff
 
 The plugin has two paths to the same Server:
 
 - a prompt hook asks the Runtime to prepare one final, bounded context value, then independently captures the
   user's prompt as Source evidence;
-- MCP gives Codex explicit tools to remember, search, revise, retire, and audit Memory.
+- MCP gives Codex explicit tools to read and maintain Memory, plus an explicit Handoff workflow.
 
 Memory scope comes from the normalized Git remote when one is available, or from the project path otherwise. A later
 Codex session opened in the same project resolves the same scope. Set `POWERCONTEXT_CODEX_SCOPE_ID` only when you need
@@ -34,7 +34,14 @@ an explicit scope that is independent of both.
 The Hook calls `POST /v1/context/prepare` once before Codex analyzes the prompt. It requests an 8000-byte total budget,
 strictly validates `powercontext.prepared-context.v1`, and injects the returned content unchanged. The Runtime labels
 Memory-derived items as untrusted history, preserves exact citations, and owns final selection and rendering. Explicit
-search remains available through the Client and MCP; it is not a second automatic recall step.
+search remains available through the Client and MCP; it is not a second automatic recall step. Automatically injected
+content and Handoffs are historical information. Codex must still check current code, user requests, and system
+instructions before acting on them.
+
+Memory stores durable, reusable decisions, constraints, and state. A Handoff temporarily transfers the current task to
+another task, session, or model. It must be explicitly prepared, inspected, and delivered, rather than substituted with
+a few Memory entries. Read [Memory and Handoff](../explanation/memory-and-handoff.md) for the boundary and
+[Hand off work in Codex](handoff-with-codex.md) for the procedure.
 
 ## Control prompt capture
 

docs/en/docs/how-to/handoff-with-codex.md

@@ -0,0 +1,45 @@
+---
+title: Hand off work in Codex
+description: Explicitly transfer the verifiable state of current work to another task, session, or model.
+---
+
+# Hand off work in Codex
+
+Use a Handoff to explicitly transfer current work to another Codex task, later session, or model. When you finish, the
+receiver gets inspected temporary content that includes the objective, verified progress, blockers, next action, and
+evidence.
+
+## Before you start
+
+Complete [Install and run](install-and-run.md), keep the Server running, and start a Codex session with the
+PowerContext plugin configured in the current project. Handoff content belongs to the current project scope. The
+receiving task should continue in that project or receive the complete Prepared Handoff.
+
+## 1. State the handoff boundary
+
+Tell Codex the boundary of the transfer and what the receiver needs. For example:
+
+> Prepare a PowerContext Handoff for this task. Record the objective, verified progress, current blockers, and next
+> action; inspect every statement in the draft for evidence, then give the completed handoff to the next task.
+
+Include the current task's objective, verified progress, blockers, and next action. Do not put secrets, access tokens,
+or other sensitive information in the handoff.
+
+## 2. Inspect the handoff draft
+
+Codex captures a concise current-state Source and activates the Handoff. Inspect the generated Draft and correct
+missing, stale, or unsupported statements. A repeated boundary can return `ignored`, which means that the Source has
+already been used.
+
+## 3. Give it to the receiving task
+
+After the inspection, Codex finalizes the Handoff. Give the resulting Prepared Handoff to the receiving task unchanged.
+The receiver treats it as untrusted history, checks it against the current repository, user request, and system
+instructions, then continues the work.
+
+## 4. Make it durable only when needed
+
+Handoff Drafts and Prepared Handoffs are temporary carriers and do not automatically become durable project knowledge.
+Ask Codex to commit a Handoff only when the user explicitly wants to preserve a milestone. Use Memory for durable,
+searchable decisions, constraints, state, or next steps. Read [Memory and Handoff](../explanation/memory-and-handoff.md)
+for the distinction.

docs/en/docs/how-to/install-and-run.md

@@ -24,6 +24,9 @@ powercontext setup codex --source oceanbase/powercontext --ref <ref>
 powercontext setup dsh --source oceanbase/powercontext --ref <ref>
 ```
 
+For host-specific options, see [Configure Codex](configure-codex.md) and
+[Configure DeepSeek Harness](configure-dsh.md).
+
 ## Run the local Server
 
 ```bash
@@ -52,8 +55,9 @@ powercontext capabilities
 `doctor` checks the installed package, Server liveness, and Server readiness without requiring an integration. Server
 readiness covers the database and each configured inference provider. Runtime or database failures return
 `not_ready`; an inference failure returns `degraded` without removing database-backed operations from traffic.
-`doctor codex` and `doctor dsh` separately check the optional host CLI and PowerContext plugin. The content commands exercise the
-public HTTP SDK path.
+`doctor codex` and `doctor dsh` separately check the optional host CLI and PowerContext plugin. `ready` and
+`capabilities` show the readiness and enabled capabilities of the running service. For complete status definitions and
+recovery steps, see [Troubleshoot](troubleshoot.md).
 
 ## Update or replace an installation
 

docs/en/docs/index.md

@@ -5,19 +5,23 @@ description: Install PowerContext, connect Codex, and choose the right integrati
 
 # PowerContext documentation
 
-PowerContext stores project-scoped context for agents. It runs as a local or remote Server and exposes the same
-durable Memory through Codex, Claude Code, DeepSeek Harness, Python, HTTP, and MCP.
+PowerContext stores project context that people and agents can use in later tasks. It runs as a local or remote Server
+and exposes the same persisted data through Codex, Claude Code, DeepSeek Harness, Python, HTTP, and MCP.
 
-If you are installing PowerContext for yourself, start with the [Codex quickstart](tutorials/codex-quickstart.md). It
-takes you from a Git install to a second Codex session that can restore the first session's work.
+If this is your first use, start with the [Codex quickstart](tutorials/codex-quickstart.md). When you finish, you can
+read and maintain Memory in a later Codex session for the same project.
 
-## Use PowerContext
+## Choose your path
 
-- [Install and run](how-to/install-and-run.md): install from Git, start the Server, and update it.
-- [Configure Codex](how-to/configure-codex.md): install the plugin and control project scope and prompt capture.
-- [Configure Claude Code](how-to/configure-claude-code.md): install the plugin and share project Memory with Codex.
-- [Configure DeepSeek Harness](how-to/configure-dsh.md): install the DSH plugin and control project scope and prompt capture.
-- [Troubleshoot](how-to/troubleshoot.md): diagnose credentials, plugin, Server, database, and hook failures.
+- For an end-to-end first experience, read the [Codex quickstart](tutorials/codex-quickstart.md).
+- To install, start, update, or relocate a local service, read [Install and run](how-to/install-and-run.md).
+- To control project scope, prompt capture, or local authentication, read [Configure Codex](how-to/configure-codex.md).
+- To configure another host, read [Configure Claude Code](how-to/configure-claude-code.md) or
+  [Configure DeepSeek Harness](how-to/configure-dsh.md).
+- To understand the boundary between durable Memory and a temporary Handoff, read
+  [Memory and Handoff](explanation/memory-and-handoff.md).
+- To transfer current work to another task, session, or model, read [Hand off work in Codex](how-to/handoff-with-codex.md).
+- For installation, Server, plugin, or Hook failures, read [Troubleshoot](how-to/troubleshoot.md).
 
 ## Look up details
 

docs/en/docs/tutorials/codex-quickstart.md

@@ -5,15 +5,15 @@ description: Install PowerContext and carry project context across Codex session
 
 # Codex quickstart
 
-This tutorial installs PowerContext without requiring you to clone the repository, connects Codex, and proves that
-Memory survives across sessions.
+This tutorial installs PowerContext without requiring you to clone the repository. When you finish, you will read,
+revise, and retire Memory saved from the first Codex session in a second session for the same project.
 
 ## Before you start
 
 You need macOS or Linux, `uv`, Codex CLI, and read access to the PowerContext Git URL. Confirm that Git can reach the
 repository with the credentials already configured on your machine.
 
-## 1. Install and configure
+## 1. Install the tool and plugin
 
 Run these commands from any directory:
 
@@ -23,7 +23,7 @@ powercontext setup codex --source oceanbase/powercontext --ref master
 ```
 
 The first command installs an isolated application. The second installs the Codex plugin and prepares PowerContext's
-user data directory.
+user data directory. For installation, updates, and data locations, see [Install and run](../how-to/install-and-run.md).
 
 ## 2. Start the Server
 
@@ -33,7 +33,8 @@ Keep this process running in its own terminal:
 powercontext server run
 ```
 
-The default service listens at `http://127.0.0.1:8000`. It creates a persistent SQLite database on first start.
+The default service listens at `http://127.0.0.1:8000`. It creates a persistent SQLite database on first start. Keep
+this terminal running.
 
 Check the whole installation from another terminal:
 
@@ -42,37 +43,41 @@ powercontext doctor
 powercontext doctor codex
 ```
 
-Every line from both commands should report `ok`. The first command checks the package and Server dependencies; the
-second checks the optional Codex integration.
+Every line from both commands should report `ok`. The first checks the package and Server; the second checks only the
+optional Codex integration. If a result is `degraded` or `failed`, read [Troubleshoot](../how-to/troubleshoot.md).
 
-## 3. Save a handoff
+## 3. Save project Memory
 
 Start a new Codex session in a project directory. If Codex asks whether to trust the PowerContext hook, open `/hooks`
 and approve it.
 
 Ask Codex:
 
-> Use PowerContext to save three separate handoff entries: the outcome is “the parser accepts TOML”; the current state
+> Use PowerContext to save three separate project Memory entries: the outcome is “the parser accepts TOML”; the current state
 > is “tests pass on Python 3.11”; the next step is “add malformed-input cases”.
 
 Codex should use the project-context skill and confirm the successful Memory writes. Do not put secrets in Memory.
 
-## 4. Restore and update it
+## 4. Read and update it in a later session
 
 End that session and start another one in the same project. Ask:
 
-> Restore the PowerContext handoff for this project. Then revise the next step to “document malformed-input errors”
+> List the active PowerContext Memory for this project. Then revise the next step to “document malformed-input errors”
 > and retire the old current-state entry.
 
-The second session should recover the three entries before changing them. Revision and retirement preserve history;
+The second session should list the three active entries before changing them. Revision and retirement preserve history;
 they do not overwrite or delete old versions.
 
 Start a third session and ask:
 
-> List the active PowerContext memory for this project.
+> List the active PowerContext Memory for this project.
 
 The revised next step should be active. The retired current state and superseded next step should not appear in the
-active list.
+active list. This shows that the project scope remains consistent across Codex sessions.
+
+This tutorial verifies durable Memory. Read [Memory and Handoff](../explanation/memory-and-handoff.md) for the
+distinction between Memory and a temporary Handoff. To transfer a complete work package to another task, session, or
+model, use [Hand off work in Codex](../how-to/handoff-with-codex.md).
 
 ## 5. Check graceful degradation
 

docs/zh/docs/explanation/memory-and-handoff.md

@@ -0,0 +1,35 @@
+---
+title: 理解 Memory 和 Handoff
+description: 了解长期项目 Memory 与临时工作 Handoff 的不同用途和边界。
+---
+
+# 理解 Memory 和 Handoff
+
+PowerContext 提供长期项目 Memory 和临时 Handoff。后续任务会用到的内容不同，因此两者的用途也不同。
+
+## Memory：长期项目知识
+
+Memory 保存后续任务仍可能需要的、可独立理解的信息，例如决策、约束、当前状态和下一步。它属于项目 scope，可被检索，
+也可以修订或停用；修订和停用保留历史，不会静默覆盖旧记录。
+
+用户明确要求保存时，Codex 才应写入 Memory。Prompt Hook 会采集提示词作为 Source 证据，但采集不等同于自动创建
+Memory，也不应为了复制当前提示词而额外写入一条 Memory。
+
+## Handoff：临时工作交接
+
+Handoff 将一个任务当前的目标、已验证进度、阻塞项、下一步和证据组织为可交给接手者的临时内容。它需要显式准备、检查
+和完成；接手者应收到完整的 Prepared Handoff，并先核对当前代码和指令。
+
+Draft 和 Prepared Handoff 默认不是长期项目知识。只有用户明确要求保留某个里程碑时，才提交 Handoff。
+
+## 如何选择
+
+| 你的需求 | 使用 |
+| --- | --- |
+| 后续项目工作仍需了解一项决策、约束或下一步 | Memory |
+| 把正在进行的任务完整交给另一个任务、会话或模型 | Handoff |
+| 记录用户当前提示词作为处理证据 | 让 Prompt Hook 采集 Source |
+| 保存已经验证、需要长期复用的交接里程碑 | 经用户要求提交 Handoff，或保存为 Memory |
+
+无论使用哪一种，都不要存储密钥、访问令牌或其他敏感信息。使用 Handoff 的具体步骤见
+[在 Codex 中交接工作](../how-to/handoff-with-codex.md)。