oceanbase · chenncy · Sep 1, 2026
diff --git a/docs/en/docs/explanation/core-concepts.md b/docs/en/docs/explanation/core-concepts.md
@@ -55,7 +55,7 @@ apply after another writer changes the proposal.
 
 Approval writes an immutable Artifact Revision and returns its exact `result_artifact`. Rejection records a decision
 reason without creating an Artifact. Both decisions are terminal. See
-[Review Candidates](../how-to/review-candidates.md) for the procedure.
+[Review Candidates](/en/docs/how-to/review-candidates/) for the procedure.
 
 ## Experience and Skill have different availability
 
@@ -89,7 +89,7 @@ inspected boundary and returns a temporary Prepared Handoff. Committing a Handof
 the user wants a milestone. The receiver resolves the Handoff and records an Acknowledgement; a Task Outcome preserves
 the final status and checks as Source evidence.
 
-The [Handoff Report](../how-to/use-handoff-report.md) projects current Handoff Revisions for inspection and export. The
+The [Handoff Report](/en/docs/how-to/use-handoff-report/) projects current Handoff Revisions for inspection and export. The
 current scope report does not yet include Activity events or period comparison, and it does not rewrite Memory or the
 underlying Handoff history.
 
@@ -103,6 +103,6 @@ Model generation, human Review, and execution authority remain separate. A model
 approve an Artifact Revision, and export can create a host-local copy. None of those steps grants an Agent permission
 to execute instructions.
 
-Use [Interfaces](../reference/interfaces.md) for current surface availability and
-[Configuration](../reference/configuration.md) for exact settings and defaults. RFCs record design decisions and may
+Use [Interfaces](/en/docs/reference/interfaces/) for current surface availability and
+[Configuration](/en/docs/reference/configuration/) for exact settings and defaults. RFCs record design decisions and may
 not describe the current implementation.
diff --git a/docs/en/docs/explanation/experience-and-skill-lifecycle.md b/docs/en/docs/explanation/experience-and-skill-lifecycle.md
@@ -66,6 +66,6 @@ approval reports a conflict. The reviewer must inspect the new head before decid
 Earlier approved Revisions remain available for exact reads. An exported Skill directory is only a copy of one exact
 Revision; the managed Artifact remains the content authority.
 
-Use [Review Candidates](../how-to/review-candidates.md) for the review procedure,
-[Create and review an Experience](../how-to/create-and-review-experience.md) for Experience operations, and
-[Create and export a managed Skill](../how-to/create-and-export-skill.md) for Skill operations.
+Use [Review Candidates](/en/docs/how-to/review-candidates/) for the review procedure,
+[Create and review an Experience](/en/docs/how-to/create-and-review-experience/) for Experience operations, and
+[Create and export a managed Skill](/en/docs/how-to/create-and-export-skill/) for Skill operations.
diff --git a/docs/en/docs/explanation/memory-and-handoff.md b/docs/en/docs/explanation/memory-and-handoff.md
@@ -37,4 +37,4 @@ explicitly asks to retain a milestone.
 | 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).
+[Hand off work in Codex](/en/docs/how-to/handoff-with-codex/).
diff --git a/docs/en/docs/how-to/configure-agent-skill-targets.md b/docs/en/docs/how-to/configure-agent-skill-targets.md
@@ -0,0 +1,39 @@
+---
+title: Configure Agent Skill targets
+description: Register explicit local Codex or Claude Code Skill directories for discovery and managed publication.
+---
+
+# Configure Agent Skill targets
+
+Register a local target before scanning external Skills or publishing an approved managed Skill from the Server UI.
+
+## 1. Set the target configuration
+
+```bash
+export POWERCONTEXT_SERVER_EXTERNAL_SKILLS='{
+  "host_id": "workstation-1",
+  "targets": [
+    {
+      "target_id": "codex-project",
+      "agent_kind": "codex",
+      "installation_scope": "project",
+      "path": "/srv/project/.agents/skills",
+      "allow_managed_publish": true
+    }
+  ]
+}'
+```
+
+Use one unique `target_id` per directory. `agent_kind` is `codex` or `claude_code`; `installation_scope` is `user`,
+`project`, or `plugin`. For Claude Code, use its Skill directory, for example `/srv/project/.claude/skills`.
+
+## 2. Restart and inspect
+
+Restart the Server, then use the Skills Library or the external Skill commands to scan the configured scope. The Server
+only scans immediate package directories under listed targets. It does not infer a home directory or install a package.
+
+`allow_managed_publish` is `false` by default. Set it to `true` only for a target where the authenticated Server may
+publish an approved managed Skill. Publication cannot select an arbitrary path or overwrite a foreign or modified
+package.
+
+For the configuration schema and compatibility form, see [Configuration](/en/docs/reference/configuration/).
diff --git a/docs/en/docs/how-to/configure-claude-code.md b/docs/en/docs/how-to/configure-claude-code.md
@@ -129,7 +129,7 @@ local project path.
 normal interactive use.
 
 The timeout and flush controls are listed in the
-[configuration reference](../reference/configuration.md#claude-code-plugin). They apply to the Hook process; the MCP
+[configuration reference](/en/docs/reference/configuration/#claude-code-plugin). They apply to the Hook process; the MCP
 client remains managed by Claude Code.
 
 ## Connect an authenticated Server

diff --git a/docs/en/docs/how-to/configure-codex.md b/docs/en/docs/how-to/configure-codex.md
@@ -67,8 +67,8 @@ 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.
+a few Memory entries. Read [Memory and Handoff](/en/docs/explanation/memory-and-handoff/) for the boundary and
+[Hand off work in Codex](/en/docs/how-to/handoff-with-codex/) for the procedure.
 
 ## Control prompt capture
 

diff --git a/docs/en/docs/how-to/configure-hermes.md b/docs/en/docs/how-to/configure-hermes.md
@@ -83,7 +83,7 @@ the file:
 | `POWERCONTEXT_HERMES_WORKSTREAM` | Read the shared Git-private Workstream binding; enabled by default |
 
 Let the Hermes wizard store authorization in its protected `.env` secret store; do not put the token in
-`config.json`. Use plain HTTP only for a loopback Server. See [Deploy the Server](deploy-server.md) before connecting
+`config.json`. Use plain HTTP only for a loopback Server. See [Deploy the Server](/en/docs/how-to/deploy-server/) before connecting
 to a remote deployment. Evaluation traces contain prompts and recalled context; keep them local and protect them as
 sensitive data.
 

diff --git a/docs/en/docs/how-to/configure-server-environment.md b/docs/en/docs/how-to/configure-server-environment.md
@@ -0,0 +1,41 @@
+---
+title: Configure a Server environment
+description: Generate, inspect, validate, and run PowerContext from an explicit environment file.
+---
+
+# Configure a Server environment
+
+Use an explicit environment file when the Server needs inference, scheduling, storage, or deployment settings.
+
+## 1. Generate the file
+
+```bash
+powercontext config init --output .env
+```
+
+The guided command writes a private file with mode `0600`. Enter provider credentials through your environment or
+secret manager, not in command-line arguments.
+
+## 2. Inspect and validate it
+
+```bash
+powercontext config show --env-file .env
+powercontext config validate --env-file .env
+```
+
+`config show` redacts recognized credentials. Validation checks the document and the selected model settings without
+printing secrets.
+
+## 3. Run the same configuration
+
+```bash
+powercontext server run --env-file .env
+```
+
+Values in the file override same-named process values. Inherited `POWERCONTEXT_SERVER_*` values missing from the file
+are ignored, so validation and launch use the same Server settings.
+
+The Server starts with the configured capabilities. Use `powercontext ready` and `powercontext capabilities` to check
+its readiness and enabled features.
+
+For every variable, default, and precedence rule, see [Configuration](../reference/configuration.md).
diff --git a/docs/en/docs/how-to/configure-vector-search.md b/docs/en/docs/how-to/configure-vector-search.md
@@ -0,0 +1,38 @@
+---
+title: Configure vector search
+description: Enable embedding-backed vector and hybrid Memory search, then verify the Runtime capability.
+---
+
+# Configure vector search
+
+Vector search needs an embedding model, a stable profile ID, and the model's output dimension.
+
+## 1. Set one embedding profile
+
+```bash
+export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_MODEL=provider:embedding-model
+export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_PROFILE_ID=embedding-model-v1
+export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_DIMENSION=1024
+```
+
+Replace the example values with one supported provider model, a profile ID you keep stable for that model, and its
+documented output dimension. `POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_NORMALIZATION` defaults to `unit`.
+
+## 2. Start the Server
+
+```bash
+powercontext server run
+```
+
+With SQLite, PowerContext loads the bundled sqlite-vec extension when it opens the database. Startup fails if the
+installed extension is incompatible with the platform or SQLite build.
+
+## 3. Verify the capability
+
+```bash
+powercontext capabilities
+```
+
+The result reports the enabled search modes. Without an embedding profile, SQLite full-text search remains available.
+
+For timeouts, batch size, storage settings, and exact defaults, see [Configuration](../reference/configuration.md).
diff --git a/docs/en/docs/how-to/deploy-server.md b/docs/en/docs/how-to/deploy-server.md
@@ -96,7 +96,8 @@ 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.
+orchestrator can probe them. API, MCP, metrics, and `/openapi.json` require authentication. The `/docs` shell remains
+public, but requests made from the interactive reference 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.

diff --git a/docs/en/docs/index.md b/docs/en/docs/index.md
@@ -4,7 +4,7 @@ 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: 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.
+  intro: Choose a tutorial to learn one complete path, a how-to guide to finish a specific task, an explanation to understand system behavior, or a reference page to look up current contracts and settings.
   sections:
     - title: Recommended learning path
       description: Complete a local API or Agent loop first, then connect another host or adopt the complete work workflow.
@@ -63,6 +63,15 @@ overview:
         - title: Configuration
           description: Set storage, providers, interfaces, and runtime behavior.
           href: en/docs/reference/configuration/
+        - title: Configure a Server environment
+          description: Generate one explicit environment file, validate it, and start the Server with the same settings.
+          href: en/docs/how-to/configure-server-environment/
+        - title: Configure vector search
+          description: Set an embedding profile and confirm that vector and hybrid search are available.
+          href: en/docs/how-to/configure-vector-search/
+        - title: Configure Agent Skill targets
+          description: Register local Codex or Claude Code Skill directories for discovery and managed publication.
+          href: en/docs/how-to/configure-agent-skill-targets/
         - title: Deploy the Server
           description: Run a persistent Server with health checks, authentication, and a safe network boundary.
           href: en/docs/how-to/deploy-server/

diff --git a/docs/en/docs/reference/configuration.md b/docs/en/docs/reference/configuration.md
@@ -6,26 +6,13 @@ description: PowerContext paths, Server, Client, inference, and Agent integratio
 # Configuration
 
 PowerContext reads configuration from environment variables when each process starts. The CLI does not search for a
-`.env` file automatically. Export values in the shell, have the service manager or container supply them, or pass an
-explicit file to a command that accepts `--env-file`. An Agent host may load its own environment file according to
-that host's rules.
+`.env` file automatically. A command that accepts `--env-file` reads only the values in that file for Server settings;
+values in the file override same-named process values. Agent hosts can load their own environment files according to
+their host-specific rules.
 
-## Explicit environment files
-
-Create a guided configuration, inspect it without printing credentials, and validate it before launch:
-
-```bash
-powercontext config init --output .env
-powercontext config show --env-file .env
-powercontext config validate --env-file .env
-powercontext server run --env-file .env
-```
-
-`config init` writes the file with mode `0600`. When `server run` receives `--env-file`, assignments in that file
-override same-named process values. Inherited `POWERCONTEXT_SERVER_*` values that are missing from the file are
-ignored, so validation and launch use the same Server configuration. `config show` redacts recognized and
-generator-recorded credentials; still treat the file itself as a secret-bearing deployment artifact. See the
-[Full-capability Quick Start](../how-to/full-capability-runtime.md) for the guided setup and verification flow.
+For the configuration-file workflow, including generation, redacted inspection, validation, and launch, see
+[Configure a Server environment](../how-to/configure-server-environment.md). Treat every environment file as a
+secret-bearing deployment artifact.
 
 ## User data
 
@@ -114,15 +101,6 @@ Handoff Report is independently enabled by default at `/handoff-reports`. When n
 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.
 
-Example with a controlled SQLite path and scheduled extraction:
-
-```bash
-export POWERCONTEXT_SERVER_DATABASE_URL=sqlite+aiosqlite:////srv/powercontext/runtime.db
-export POWERCONTEXT_SERVER_RUNTIME_SCHEDULE_SECONDS=30
-export POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL=provider:model-name
-powercontext server run
-```
-
 Provider credentials, such as `OPENAI_API_KEY`, are read by the configured inference provider. Do not place secrets in
 command-line arguments, documentation, or Memory. Replace `provider:model-name` with a model identifier supported by
 Pydantic AI. Scheduled extraction requires both a generation model and
@@ -170,15 +148,8 @@ The same configured generation model gates explicit Experience generation, manag
 and external Skill import or fork. Without it, these operations return a capability error before persisting a
 Candidate. Candidate Review, exact reads, and external Skill scan/list/resolve continue to work.
 
-Experience incubation is a separate APScheduler job with its own persisted Source cursor. Enable it with:
-
-```bash
-export POWERCONTEXT_SERVER_RUNTIME_EXPERIENCE_SCHEDULE_SECONDS=30
-export POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL=provider:model-name
-powercontext server run
-```
-
-Each activation inspects a fixed window of at most 32 Sources and exposes only Content Sources whose metadata contains
+Experience incubation is a separate APScheduler job with its own persisted Source cursor. Each activation inspects a
+fixed window of at most 32 Sources and exposes only Content Sources whose metadata contains
 `"kind": "task-outcome"` to the model. It creates pending Experience Candidates in the Review Inbox; it does not
 approve them, place them in PreparedContext, create a managed Skill, export it to an Agent target, or execute anything.
 The Memory and Experience jobs share the APScheduler sidecar under `POWERCONTEXT_HOME`, but keep independent job
@@ -187,29 +158,9 @@ See [Create and review an Experience](../how-to/create-and-review-experience.md)
 
 ### Agent Skill targets
 
-Configure Codex and Claude Code host-local targets as one JSON value:
-
-```bash
-export POWERCONTEXT_SERVER_EXTERNAL_SKILLS='{
-  "host_id": "workstation-1",
-  "targets": [
-    {
-      "target_id": "codex-project",
-      "agent_kind": "codex",
-      "installation_scope": "project",
-      "path": "/srv/project/.agents/skills",
-      "allow_managed_publish": true
-    },
-    {
-      "target_id": "claude-project",
-      "agent_kind": "claude_code",
-      "installation_scope": "project",
-      "path": "/srv/project/.claude/skills",
-      "allow_managed_publish": true
-    }
-  ]
-}'
-```
+`POWERCONTEXT_SERVER_EXTERNAL_SKILLS` is a JSON object containing one local host identity and explicit Codex or Claude
+Code Skill targets. For its JSON shape and verification steps, see
+[Configure Agent Skill targets](../how-to/configure-agent-skill-targets.md).
 
 Target IDs must be unique. `agent_kind` supports `codex` and `claude_code`; installation scopes are `user`, `project`,
 and `plugin`. PowerContext scans only the immediate Skill package directories under these explicit targets; it does not
@@ -239,46 +190,13 @@ export POWERCONTEXT_SERVER_DATABASE_URL="$OCEANBASE_URL"
 The URL must use the `mysql+aoceanbase` driver, include an explicit port and database, and set `charset=utf8mb4`. The
 tenant must use MySQL compatibility mode.
 
-### Embeddings
-
-Embedding search is enabled only when all three identity fields are set:
-
-```bash
-export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_MODEL=provider:embedding-model
-export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_PROFILE_ID=embedding-model-v1
-export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_DIMENSION=1024
-```
-
-Replace the example values with the selected provider model, a stable profile ID, and that model's dimension.
-
-Optional settings are `POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_NORMALIZATION` and
-`POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_TIMEOUT_SECONDS`.
-
-Embedding normalization defaults to `unit`.
-
-### SQLite vector search
-
-SQLite vector and hybrid search use [sqlite-vec](https://alexgarcia.xyz/sqlite-vec/), which is bundled with the
-`powercontext[builtin]` dependency set. Configure the complete embedding profile; no extension path is needed:
-
-```bash
-export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_MODEL=provider:embedding-model
-export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_PROFILE_ID=embedding-model-v1
-export POWERCONTEXT_SERVER_INFERENCE_EMBEDDING_DIMENSION=1024
-export POWERCONTEXT_SERVER_DATABASE_URL=sqlite+aiosqlite:////srv/powercontext/powercontext.db
-powercontext server run
-```
-
-PowerContext loads and probes the bundled extension when the Server opens the database. Startup fails if the package
-does not contain a library compatible with the current platform or SQLite build.
-
-In another terminal, confirm that the initialized runtime reports vector and hybrid search:
-
-```bash
-powercontext capabilities
-```
+### Embeddings and SQLite vector search
 
-SQLite full-text search remains available when no embedding model is configured.
+Vector search requires all three embedding identity variables: model, stable profile ID, and positive dimension.
+Normalization defaults to `unit`; timeout and batch size are optional controls. SQLite vector and hybrid search use the
+bundled sqlite-vec extension. The Server probes it when opening the database, and startup fails if the installed library
+is incompatible with the platform or SQLite build. Full-text search remains available without an embedding profile.
+For configuration and capability verification, see [Configure vector search](../how-to/configure-vector-search.md).
 
 ## CLI Server connection