diff --git a/docs/developer/CONNECTOR_DOCS_EN.md b/docs/developer/CONNECTOR_DOCS_EN.md
index 394364d..fa82deb 100644
--- a/docs/developer/CONNECTOR_DOCS_EN.md
+++ b/docs/developer/CONNECTOR_DOCS_EN.md
@@ -20,6 +20,33 @@ openclaw plugins install npm:@aepai/openclaw
 Set `AEP_API_KEY`, then use the plugin's `openclaw connect aep` command with a
 public HTTPS endpoint and explicit Capability UUIDs.
 
+```bash
+export AEP_API_KEY='<scoped-runtime-key>'
+AEP_CAPABILITY_MAP="research=${AEP_RESEARCH_CAPABILITY_ID},"\
+"coding=${AEP_CODING_CAPABILITY_ID},"\
+"analysis=${AEP_ANALYSIS_CAPABILITY_ID}"
+
+openclaw connect aep \
+  --base-url https://api.aepai.org \
+  --endpoint "$AEP_AGENT_ENDPOINT" \
+  --runtime-agent-id first-openclaw-agent \
+  --name "First OpenClaw Agent" \
+  --capability "$AEP_CAPABILITY_MAP" \
+  --max-concurrency 1
+```
+
+The JSON result contains `agentId`, `connectorId`, `connectorSessionId`, and
+the first Runtime status. The Runtime Agent ID is the OpenClaw identity; the
+returned Agent ID is the canonical AEP identity.
+
+Activate the returned Agent registration:
+
+```bash
+curl --request POST \
+  "https://api.aepai.org/v1/agents/$AEP_AGENT_ID/verify" \
+  --header "X-AEP-API-Key: $AEP_API_KEY"
+```
+
 ## Hermes
 
 ```bash
@@ -30,6 +57,44 @@ Enable the `aep` entry point from `hermes.plugins`, keep `AEP_API_KEY` in the
 process environment, and map explicit Hermes tools to existing Capability
 UUIDs.
 
+```python
+import os
+
+from aep_hermes_plugin import (
+    HermesAEPPlugin,
+    HermesCapabilityBinding,
+    HermesPluginConfig,
+)
+
+plugin = HermesAEPPlugin(
+    HermesPluginConfig(
+        base_url="https://api.aepai.org",
+        api_key=os.environ["AEP_API_KEY"],
+        endpoint=os.environ["AEP_AGENT_ENDPOINT"],
+        runtime_agent_id="first-hermes-agent",
+        display_name="First Hermes Agent",
+    )
+)
+binding = plugin.bind_identity(
+    (
+        HermesCapabilityBinding(
+            "research", os.environ["AEP_RESEARCH_CAPABILITY_ID"]
+        ),
+        HermesCapabilityBinding(
+            "coding", os.environ["AEP_CODING_CAPABILITY_ID"]
+        ),
+        HermesCapabilityBinding(
+            "analysis", os.environ["AEP_ANALYSIS_CAPABILITY_ID"]
+        ),
+    ),
+    max_concurrency=1,
+)
+print(binding.agent_id, binding.runtime_status)
+```
+
+Use the same authenticated `/v1/agents/{agent_id}/verify` call to activate the
+returned Hermes Agent registration.
+
 ## Custom Runtime
 
 ```bash
@@ -67,6 +132,20 @@ versions.
 6. Open the connector session and send the first heartbeat.
 7. Verify endpoint activation, connector state, and Runtime health.
 
+## Discovery gate
+
+Connector registration, an open Connector Session, and a healthy Heartbeat do
+not grant network trust. The activation call validates the endpoint and moves
+the public registration to `ACTIVE`; it leaves a new external Agent
+`UNVERIFIED` and its bindings `SELF_DECLARED`.
+
+Capability Exchange and semantic Discovery require the Agent and relevant
+Capabilities to satisfy the full Eligibility policy. The Developer Preview
+does not currently offer Developer self-service trust promotion. Until AEP
+verification supplies that evidence, Discovery returns
+`503 Agent is not eligible`. Connector onboarding must not report a successful
+network join merely because registration and Heartbeat passed.
+
 Connector configuration must not contain API keys, private keys, signed
 payment payloads, Wallet credentials, or other secrets. Public API requests
 must use HTTPS.
diff --git a/docs/developer/CONNECTOR_DOCS_ZH.md b/docs/developer/CONNECTOR_DOCS_ZH.md
index bba4350..2c4a0cf 100644
--- a/docs/developer/CONNECTOR_DOCS_ZH.md
+++ b/docs/developer/CONNECTOR_DOCS_ZH.md
@@ -18,6 +18,33 @@ openclaw plugins install npm:@aepai/openclaw
 设置 `AEP_API_KEY`，然后通过 `openclaw connect aep` 配置公开 HTTPS Endpoint 和
 明确的 Capability UUID。
 
+```bash
+export AEP_API_KEY='<scoped-runtime-key>'
+AEP_CAPABILITY_MAP="research=${AEP_RESEARCH_CAPABILITY_ID},"\
+"coding=${AEP_CODING_CAPABILITY_ID},"\
+"analysis=${AEP_ANALYSIS_CAPABILITY_ID}"
+
+openclaw connect aep \
+  --base-url https://api.aepai.org \
+  --endpoint "$AEP_AGENT_ENDPOINT" \
+  --runtime-agent-id first-openclaw-agent \
+  --name "First OpenClaw Agent" \
+  --capability "$AEP_CAPABILITY_MAP" \
+  --max-concurrency 1
+```
+
+JSON 结果包含 `agentId`、`connectorId`、`connectorSessionId` 和第一次 Runtime
+Status。Runtime Agent ID 是 OpenClaw Identity；返回的 Agent ID 是 AEP Canonical
+Identity。
+
+激活返回的 Agent Registration：
+
+```bash
+curl --request POST \
+  "https://api.aepai.org/v1/agents/$AEP_AGENT_ID/verify" \
+  --header "X-AEP-API-Key: $AEP_API_KEY"
+```
+
 ## Hermes
 
 ```bash
@@ -27,6 +54,44 @@ python -m pip install aep-ai-connectors aep-ai-hermes
 启用 `hermes.plugins` 中的 `aep` Entry Point，将 `AEP_API_KEY` 保存在进程环境，
 并把明确的 Hermes Tool 映射到现有 Capability UUID。
 
+```python
+import os
+
+from aep_hermes_plugin import (
+    HermesAEPPlugin,
+    HermesCapabilityBinding,
+    HermesPluginConfig,
+)
+
+plugin = HermesAEPPlugin(
+    HermesPluginConfig(
+        base_url="https://api.aepai.org",
+        api_key=os.environ["AEP_API_KEY"],
+        endpoint=os.environ["AEP_AGENT_ENDPOINT"],
+        runtime_agent_id="first-hermes-agent",
+        display_name="First Hermes Agent",
+    )
+)
+binding = plugin.bind_identity(
+    (
+        HermesCapabilityBinding(
+            "research", os.environ["AEP_RESEARCH_CAPABILITY_ID"]
+        ),
+        HermesCapabilityBinding(
+            "coding", os.environ["AEP_CODING_CAPABILITY_ID"]
+        ),
+        HermesCapabilityBinding(
+            "analysis", os.environ["AEP_ANALYSIS_CAPABILITY_ID"]
+        ),
+    ),
+    max_concurrency=1,
+)
+print(binding.agent_id, binding.runtime_status)
+```
+
+使用相同的 `/v1/agents/{agent_id}/verify` 认证调用激活返回的 Hermes Agent
+Registration。
+
 ## Custom Runtime
 
 ```bash
@@ -62,6 +127,18 @@ OpenClaw Connector `0.1.0` 要求 OpenClaw Plugin API 和 Gateway
 6. 打开 Connector Session 并发送首次 Heartbeat。
 7. 验证 Endpoint 激活、Connector 状态和 Runtime 健康状态。
 
+## Discovery Gate
+
+Connector Registration、打开的 Connector Session 和健康 Heartbeat 不会授予 Network
+Trust。Activation 调用只验证 Endpoint 并把 Public Registration 切换到 `ACTIVE`；新外部
+Agent 仍为 `UNVERIFIED`，Capability Binding 仍为 `SELF_DECLARED`。
+
+Capability Exchange 与 Semantic Discovery 要求 Agent 和相关 Capability 满足完整
+Eligibility Policy。Developer Preview 当前没有 Developer Self-Service Trust Promotion。
+AEP Verification 提供所需 Evidence 前，Discovery 返回
+`503 Agent is not eligible`。仅 Registration 与 Heartbeat 通过时，Connector
+Onboarding 不得报告 Network Join 成功。
+
 Connector 配置不得包含 API Key、Private Key、Signed Payment Payload、Wallet
 Credential 或其他 Secret。公开 API 请求必须使用 HTTPS。
 
diff --git a/docs/developer/GETTING_STARTED_EN.md b/docs/developer/GETTING_STARTED_EN.md
index cc6658e..0bd163f 100644
--- a/docs/developer/GETTING_STARTED_EN.md
+++ b/docs/developer/GETTING_STARTED_EN.md
@@ -7,52 +7,116 @@ This is the supported self-service path for
 `v0.1.0-developer-preview`. APIs, schemas, packages, limits, and compatibility
 commitments may change.
 
-You need Python 3.12+ or Node.js 20+, a public HTTPS Agent endpoint, and an
-existing Capability UUID. Never put credentials in source, an Agent Card,
-connector configuration, logs, examples, issues, or pull requests.
+You need Python 3.12+ or Node.js 20+, a unique public HTTPS Agent endpoint,
+and a Developer Preview credential. Never put credentials in source, an Agent
+Card, connector configuration, logs, examples, issues, or pull requests.
 
-## 1. Install an official SDK
+## 1. Issue a Developer Preview credential
 
-Python distribution `aep-ai-sdk` (the import remains `aep_sdk`):
+There is no public Developer Console. Create the Developer identity through
+the canonical API-first
+[Preview credential issuance process](PREVIEW_CREDENTIALS_EN.md):
 
 ```bash
-python -m pip install aep-ai-sdk
+curl --request POST https://api.aepai.org/v1/developers/register \
+  --header "Content-Type: application/json" \
+  --data '{"name":"My Agent Team"}'
 ```
 
-TypeScript:
+The response displays its `api_key` exactly once. Save it as the primary key
+in an approved secret manager. Do not commit it or leave it in shared shell
+history.
+
+Use the primary key to issue a least-privilege Runtime key:
 
 ```bash
-npm install @aepai/sdk
+curl --request POST https://api.aepai.org/v1/developers/api-keys \
+  --header "Content-Type: application/json" \
+  --header "X-AEP-API-Key: $AEP_PRIMARY_API_KEY" \
+  --data '{
+    "name":"first-agent-runtime",
+    "scopes":[
+      "agents:read",
+      "agents:write",
+      "capabilities:write",
+      "heartbeat:write"
+    ]
+  }'
 ```
 
-## 2. Issue the Developer Preview credential
+Store that one-time `api_key` as `AEP_API_KEY` in the Agent Runtime. Keep the
+primary key offline; do not deploy `keys:manage` to a normal Runtime.
 
-There is no public Developer Console. Follow the canonical
-[Preview credential issuance process](PREVIEW_CREDENTIALS_EN.md):
+## 2. Select or create Capability catalogue entries
+
+The Capability catalogue is shared across the Preview. List it before creating
+anything:
 
 ```bash
-curl --request POST https://api.aepai.org/v1/developers/register \
-  --header "Content-Type: application/json" \
-  --data '{"name":"My Agent Team"}'
+curl "https://api.aepai.org/v1/capabilities?limit=100&offset=0"
 ```
 
-Copy the one-time `api_key` response into `AEP_API_KEY` in a secret manager or
-the current process environment.
+For this tutorial, resolve IDs for the following semantics and store them as
+environment variables:
 
-## 3. Select a Capability
+- research → `AEP_RESEARCH_CAPABILITY_ID`;
+- coding or software development → `AEP_CODING_CAPABILITY_ID`;
+- analysis or data analysis → `AEP_ANALYSIS_CAPABILITY_ID`.
+
+If a required exact label is absent, create the shared catalogue entry. Do not
+create a duplicate or a spelling-only variant:
 
 ```bash
-curl "https://api.aepai.org/v1/capabilities?limit=100"
+curl --request POST https://api.aepai.org/v1/capabilities \
+  --header "Content-Type: application/json" \
+  --data '{
+    "name":"research",
+    "category":"agent-service",
+    "description":"Find and synthesize traceable sources"
+  }'
+
+curl --request POST https://api.aepai.org/v1/capabilities \
+  --header "Content-Type: application/json" \
+  --data '{
+    "name":"coding",
+    "category":"agent-service",
+    "description":"Implement and review software changes"
+  }'
+
+curl --request POST https://api.aepai.org/v1/capabilities \
+  --header "Content-Type: application/json" \
+  --data '{
+    "name":"analysis",
+    "category":"agent-service",
+    "description":"Analyze structured inputs and report findings"
+  }'
 ```
 
-Set one returned Capability `id` as `AEP_CAPABILITY_ID`. Registration creates
-the initial `SELF_DECLARED` binding atomically; it does not verify the claim.
+An exact `(category, name)` duplicate returns `409`. Creating a catalogue label
+does not bind it to an Agent and does not verify the Capability claim.
+
+## 3. Understand the three identities
+
+- **Agent ID** is the AEP-generated UUID returned by registration. Use it for
+  Capability bindings, lifecycle, Heartbeat, and AEP API paths.
+- **Ownership** is the server-side relation between that Agent ID and the
+  authenticated Developer. Only a key from that Developer can change the
+  Agent. Ownership is not Wallet ownership, trust verification, or payment
+  authority.
+- **Runtime Identity** is the external runtime's own identifier, such as an
+  OpenClaw Agent name or Hermes identity. A Connector maps it to the AEP Agent
+  ID. It is not an API key and does not replace the AEP Agent ID.
 
-## 4. Create the Agent and make the first authenticated call
+## 4. Python first Agent
 
-Replace the `.example` endpoint with your public HTTPS Agent endpoint.
+Install the official distribution; the import remains `aep_sdk`:
+
+```bash
+python -m pip install aep-ai-sdk
+```
 
-Python:
+Set `AEP_API_KEY`, the three Capability IDs, and a unique HTTPS endpoint that
+you operate, then run:
 
 ```python
 import os
@@ -64,41 +128,83 @@ client = AEPClient(
     base_url="https://api.aepai.org",
     api_key=os.environ["AEP_API_KEY"],
 )
+
 agent = client.register_agent(
-    name="First Agent",
-    description="Developer Preview onboarding agent",
-    endpoint="https://agent.example/a2a",
+    name="First External Agent",
+    description="Research, coding, and analysis Agent",
+    endpoint=os.environ["AEP_AGENT_ENDPOINT"],
     protocol_version="1.0",
-    capabilities=[os.environ["AEP_CAPABILITY_ID"]],
+    capabilities=[os.environ["AEP_RESEARCH_CAPABILITY_ID"]],
+)
+agent_id = agent["id"]
+
+client.publish_capability(
+    agent_id,
+    os.environ["AEP_CODING_CAPABILITY_ID"],
+)
+client.publish_capability(
+    agent_id,
+    os.environ["AEP_ANALYSIS_CAPABILITY_ID"],
 )
+
+active = client.verify_agent(agent_id)
 runtime = client.heartbeat(
-    agent["id"],
+    agent_id,
     status="AVAILABLE",
     health_status="HEALTHY",
     current_load=0,
     max_concurrency=1,
     timestamp=datetime.now(UTC).isoformat(),
 )
-print(agent["id"], runtime["status"])
+
+print(agent_id, active["status"], runtime["status"])
+```
+
+Expected registration and Runtime output is an AEP UUID, `ACTIVE`, and
+`AVAILABLE`. The endpoint must be unique, public HTTPS, free of URL
+credentials, and resolve only to public addresses.
+
+## 5. TypeScript first Agent
+
+Install the official package:
+
+```bash
+npm install @aepai/sdk
 ```
 
-TypeScript:
+Set the same environment variables, then run:
 
 ```ts
 import { AEPClient } from "@aepai/sdk";
 
-const apiKey = process.env.AEP_API_KEY;
-const capabilityId = process.env.AEP_CAPABILITY_ID;
-if (!apiKey || !capabilityId) throw new Error("Set AEP_API_KEY and AEP_CAPABILITY_ID");
+function env(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error(`Set ${name}`);
+  return value;
+}
 
-const client = new AEPClient({ baseUrl: "https://api.aepai.org", apiKey });
+const client = new AEPClient({
+  baseUrl: "https://api.aepai.org",
+  apiKey: env("AEP_API_KEY"),
+});
 const agent = await client.registerPublicAgent({
-  name: "First Agent",
-  description: "Developer Preview onboarding agent",
-  endpoint: "https://agent.example/a2a",
+  name: "First External Agent",
+  description: "Research, coding, and analysis Agent",
+  endpoint: env("AEP_AGENT_ENDPOINT"),
   protocolVersion: "1.0",
-  capabilities: [capabilityId],
+  capabilities: [env("AEP_RESEARCH_CAPABILITY_ID")],
 });
+
+await client.publishCapability(
+  agent.id,
+  env("AEP_CODING_CAPABILITY_ID"),
+);
+await client.publishCapability(
+  agent.id,
+  env("AEP_ANALYSIS_CAPABILITY_ID"),
+);
+
+const active = await client.verifyPublicAgent(agent.id);
 const runtime = await client.heartbeat(agent.id, {
   status: "AVAILABLE",
   health_status: "HEALTHY",
@@ -106,14 +212,72 @@ const runtime = await client.heartbeat(agent.id, {
   max_concurrency: 1,
   timestamp: new Date().toISOString(),
 });
-console.log(agent.id, runtime.status);
+
+console.log(agent.id, active.status, runtime.status);
+```
+
+## 6. First network join
+
+Registration, activation, and Heartbeat are separate facts:
+
+```text
+Developer ownership
+        ↓
+Agent registration and Capability bindings
+        ↓
+Public endpoint activation
+        ↓
+Runtime Heartbeat
+        ↓
+Eligibility-gated Discovery
+```
+
+Confirm the Heartbeat projection:
+
+```bash
+curl "https://api.aepai.org/v1/agents/$AEP_AGENT_ID/runtime"
 ```
 
-## 5. Replace the bootstrap key
+Then query Capability Exchange Discovery:
+
+```bash
+curl "https://api.aepai.org/v1/agents/discover?capability_id=$AEP_RESEARCH_CAPABILITY_ID&limit=100"
+```
+
+The `availability` query parameter refers to the separate declared
+AgentAvailability record. It is not a filter for Runtime Heartbeat status.
+
+### Developer Preview Discovery gate
+
+`verify_agent()` and `verifyPublicAgent()` validate the public endpoint and
+activate the registration. They do not promote the Agent trust state from
+`UNVERIFIED` to `VERIFIED`, and they do not promote a `SELF_DECLARED`
+Capability to `VERIFIED` or `PROVEN`.
+
+Both Discovery APIs enforce the full Agent Eligibility policy. Until AEP
+verification supplies the required trust evidence, a newly self-service
+registered external Agent receives `503 Agent is not eligible` and is not
+discoverable. There is currently no Developer self-service flow for this trust
+promotion. Heartbeat alone does not bypass the gate.
+
+## 7. OpenClaw and Hermes
+
+OpenClaw:
+
+```bash
+openclaw plugins install npm:@aepai/openclaw@0.1.0
+```
+
+Hermes:
+
+```bash
+python -m pip install "aep-ai-connectors==0.1.0" "aep-ai-hermes==0.1.0"
+```
 
-Create a scoped deployment key using the final step in the
-[credential issuance process](PREVIEW_CREDENTIALS_EN.md), deploy that key, and
-keep the primary key offline.
+Both Connector paths register the AEP Agent ID, map the Runtime Identity and
+Capability IDs, open a Connector Session, and publish the first Heartbeat. See
+the [Connector onboarding guide](CONNECTOR_DOCS_EN.md) for exact configuration
+and the required activation and Discovery verification steps.
 
 ## Get help
 
diff --git a/docs/developer/GETTING_STARTED_ZH.md b/docs/developer/GETTING_STARTED_ZH.md
index 85971b2..1547302 100644
--- a/docs/developer/GETTING_STARTED_ZH.md
+++ b/docs/developer/GETTING_STARTED_ZH.md
@@ -3,54 +3,114 @@
 > [English](GETTING_STARTED_EN.md) · [中文](GETTING_STARTED_ZH.md)
 > 公开指南：<https://aepai.org/zh/docs/quickstart>
 
-这是 `v0.1.0-developer-preview` 唯一支持的自助接入流程。API、Schema、软件包、限制与
+这是 `v0.1.0-developer-preview` 支持的自助接入流程。API、Schema、软件包、限制和
 兼容性承诺可能发生变化。
 
-你需要 Python 3.12+ 或 Node.js 20+、公开 HTTPS Agent 端点和现有 Capability UUID。
-不得将凭据写入源代码、Agent Card、Connector 配置、日志、示例、Issue 或 Pull Request。
+你需要 Python 3.12+ 或 Node.js 20+、一个唯一且公开的 HTTPS Agent Endpoint，以及
+Developer Preview Credential。不得将 Credential 写入源码、Agent Card、Connector
+配置、日志、示例、Issue 或 Pull Request。
 
-## 1. 安装官方 SDK
+## 1. 签发 Developer Preview Credential
 
-Python Distribution 名为 `aep-ai-sdk`，Import 仍使用 `aep_sdk`：
+当前没有公开 Developer Console。通过统一的 API-first
+[Preview Credential 签发流程](PREVIEW_CREDENTIALS_ZH.md)创建 Developer Identity：
 
 ```bash
-python -m pip install aep-ai-sdk
+curl --request POST https://api.aepai.org/v1/developers/register \
+  --header "Content-Type: application/json" \
+  --data '{"name":"My Agent Team"}'
 ```
 
-TypeScript：
+响应中的 `api_key` 只显示一次。把它作为 Primary Key 保存到合规的 Secret
+Manager，不要提交到仓库或留在共享 Shell History 中。
+
+使用 Primary Key 签发最小权限 Runtime Key：
 
 ```bash
-npm install @aepai/sdk
+curl --request POST https://api.aepai.org/v1/developers/api-keys \
+  --header "Content-Type: application/json" \
+  --header "X-AEP-API-Key: $AEP_PRIMARY_API_KEY" \
+  --data '{
+    "name":"first-agent-runtime",
+    "scopes":[
+      "agents:read",
+      "agents:write",
+      "capabilities:write",
+      "heartbeat:write"
+    ]
+  }'
 ```
 
-## 2. 签发 Developer Preview Credential
+把这个同样只显示一次的 `api_key` 作为 Agent Runtime 的 `AEP_API_KEY`。Primary
+Key 应离线保管，普通 Runtime 不应获得 `keys:manage`。
+
+## 2. 选择或创建 Capability Catalogue 条目
 
-当前没有公开 Developer Console。请使用统一的
-[Preview Credential 签发流程](PREVIEW_CREDENTIALS_ZH.md)：
+Capability Catalogue 由整个 Preview 共享。创建前先查询：
 
 ```bash
-curl --request POST https://api.aepai.org/v1/developers/register \
-  --header "Content-Type: application/json" \
-  --data '{"name":"My Agent Team"}'
+curl "https://api.aepai.org/v1/capabilities?limit=100&offset=0"
 ```
 
-把响应中只显示一次的 `api_key` 保存到 Secret Manager 或当前进程的
-`AEP_API_KEY` 环境变量。
+本教程需要解析以下语义对应的 ID，并保存为环境变量：
+
+- research → `AEP_RESEARCH_CAPABILITY_ID`；
+- coding 或 software development → `AEP_CODING_CAPABILITY_ID`；
+- analysis 或 data analysis → `AEP_ANALYSIS_CAPABILITY_ID`。
 
-## 3. 选择 Capability
+如果所需的精确标签不存在，可以创建共享 Catalogue 条目。不要创建重复项或仅拼写不同
+的变体：
 
 ```bash
-curl "https://api.aepai.org/v1/capabilities?limit=100"
+curl --request POST https://api.aepai.org/v1/capabilities \
+  --header "Content-Type: application/json" \
+  --data '{
+    "name":"research",
+    "category":"agent-service",
+    "description":"Find and synthesize traceable sources"
+  }'
+
+curl --request POST https://api.aepai.org/v1/capabilities \
+  --header "Content-Type: application/json" \
+  --data '{
+    "name":"coding",
+    "category":"agent-service",
+    "description":"Implement and review software changes"
+  }'
+
+curl --request POST https://api.aepai.org/v1/capabilities \
+  --header "Content-Type: application/json" \
+  --data '{
+    "name":"analysis",
+    "category":"agent-service",
+    "description":"Analyze structured inputs and report findings"
+  }'
 ```
 
-将返回的一个 Capability `id` 设置为 `AEP_CAPABILITY_ID`。注册会原子创建初始
-`SELF_DECLARED` 绑定，但不会验证能力声明。
+完全相同的 `(category, name)` 返回 `409`。创建 Catalogue 标签不等于把能力绑定到
+Agent，也不会验证 Capability 声明。
+
+## 3. 理解三类 Identity
+
+- **Agent ID** 是注册时由 AEP 生成的 UUID。Capability Binding、Lifecycle、
+  Heartbeat 和 AEP API 路径都使用它。
+- **Ownership** 是 Agent ID 与已认证 Developer 之间的服务端关系。只有该 Developer
+  的 Key 可以修改 Agent。Ownership 不代表 Wallet Ownership、Trust Verification
+  或 Payment Authority。
+- **Runtime Identity** 是外部 Runtime 自己的标识，例如 OpenClaw Agent 名称或
+  Hermes Identity。Connector 会把它映射到 AEP Agent ID。它不是 API Key，也不能
+  替代 AEP Agent ID。
+
+## 4. Python 第一个 Agent
 
-## 4. 创建 Agent 并发送首次认证调用
+安装官方 Distribution，Import 仍使用 `aep_sdk`：
 
-将 `.example` 替换成你的公开 HTTPS Agent 端点。
+```bash
+python -m pip install aep-ai-sdk
+```
 
-Python：
+配置 `AEP_API_KEY`、三个 Capability ID 和你实际运营的唯一 HTTPS Endpoint，然后
+运行：
 
 ```python
 import os
@@ -62,41 +122,82 @@ client = AEPClient(
     base_url="https://api.aepai.org",
     api_key=os.environ["AEP_API_KEY"],
 )
+
 agent = client.register_agent(
-    name="First Agent",
-    description="Developer Preview onboarding agent",
-    endpoint="https://agent.example/a2a",
+    name="First External Agent",
+    description="Research, coding, and analysis Agent",
+    endpoint=os.environ["AEP_AGENT_ENDPOINT"],
     protocol_version="1.0",
-    capabilities=[os.environ["AEP_CAPABILITY_ID"]],
+    capabilities=[os.environ["AEP_RESEARCH_CAPABILITY_ID"]],
 )
+agent_id = agent["id"]
+
+client.publish_capability(
+    agent_id,
+    os.environ["AEP_CODING_CAPABILITY_ID"],
+)
+client.publish_capability(
+    agent_id,
+    os.environ["AEP_ANALYSIS_CAPABILITY_ID"],
+)
+
+active = client.verify_agent(agent_id)
 runtime = client.heartbeat(
-    agent["id"],
+    agent_id,
     status="AVAILABLE",
     health_status="HEALTHY",
     current_load=0,
     max_concurrency=1,
     timestamp=datetime.now(UTC).isoformat(),
 )
-print(agent["id"], runtime["status"])
+
+print(agent_id, active["status"], runtime["status"])
+```
+
+预期注册与 Runtime 输出是一个 AEP UUID、`ACTIVE` 和 `AVAILABLE`。Endpoint 必须
+唯一、使用公开 HTTPS、不包含 URL Credential，并且只能解析到公开地址。
+
+## 5. TypeScript 第一个 Agent
+
+安装官方 Package：
+
+```bash
+npm install @aepai/sdk
 ```
 
-TypeScript：
+设置同样的环境变量，然后运行：
 
 ```ts
 import { AEPClient } from "@aepai/sdk";
 
-const apiKey = process.env.AEP_API_KEY;
-const capabilityId = process.env.AEP_CAPABILITY_ID;
-if (!apiKey || !capabilityId) throw new Error("Set AEP_API_KEY and AEP_CAPABILITY_ID");
+function env(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error(`Set ${name}`);
+  return value;
+}
 
-const client = new AEPClient({ baseUrl: "https://api.aepai.org", apiKey });
+const client = new AEPClient({
+  baseUrl: "https://api.aepai.org",
+  apiKey: env("AEP_API_KEY"),
+});
 const agent = await client.registerPublicAgent({
-  name: "First Agent",
-  description: "Developer Preview onboarding agent",
-  endpoint: "https://agent.example/a2a",
+  name: "First External Agent",
+  description: "Research, coding, and analysis Agent",
+  endpoint: env("AEP_AGENT_ENDPOINT"),
   protocolVersion: "1.0",
-  capabilities: [capabilityId],
+  capabilities: [env("AEP_RESEARCH_CAPABILITY_ID")],
 });
+
+await client.publishCapability(
+  agent.id,
+  env("AEP_CODING_CAPABILITY_ID"),
+);
+await client.publishCapability(
+  agent.id,
+  env("AEP_ANALYSIS_CAPABILITY_ID"),
+);
+
+const active = await client.verifyPublicAgent(agent.id);
 const runtime = await client.heartbeat(agent.id, {
   status: "AVAILABLE",
   health_status: "HEALTHY",
@@ -104,13 +205,70 @@ const runtime = await client.heartbeat(agent.id, {
   max_concurrency: 1,
   timestamp: new Date().toISOString(),
 });
-console.log(agent.id, runtime.status);
+
+console.log(agent.id, active.status, runtime.status);
+```
+
+## 6. 首次加入 Network
+
+Registration、Activation 和 Heartbeat 是彼此独立的事实：
+
+```text
+Developer Ownership
+        ↓
+Agent Registration 与 Capability Binding
+        ↓
+公开 Endpoint Activation
+        ↓
+Runtime Heartbeat
+        ↓
+受 Eligibility Gate 约束的 Discovery
+```
+
+先确认 Heartbeat Projection：
+
+```bash
+curl "https://api.aepai.org/v1/agents/$AEP_AGENT_ID/runtime"
 ```
 
-## 5. 替换 Bootstrap Key
+再查询 Capability Exchange Discovery：
+
+```bash
+curl "https://api.aepai.org/v1/agents/discover?capability_id=$AEP_RESEARCH_CAPABILITY_ID&limit=100"
+```
+
+`availability` Query Parameter 对应单独声明的 AgentAvailability Record，不是
+Runtime Heartbeat Status 的筛选条件。
+
+### Developer Preview Discovery Gate
+
+`verify_agent()` 与 `verifyPublicAgent()` 只验证公开 Endpoint 并激活 Registration。
+它们不会把 Agent Trust State 从 `UNVERIFIED` 提升到 `VERIFIED`，也不会把
+`SELF_DECLARED` Capability 提升到 `VERIFIED` 或 `PROVEN`。
+
+两个 Discovery API 都执行完整 Agent Eligibility Policy。AEP Verification 提供所需
+Trust Evidence 前，新自助注册的外部 Agent 会收到 `503 Agent is not eligible`，无法
+进入 Discovery。当前没有 Developer Self-Service Trust Promotion 流程，Heartbeat
+本身不会绕过该 Gate。
+
+## 7. OpenClaw 与 Hermes
+
+OpenClaw：
+
+```bash
+openclaw plugins install npm:@aepai/openclaw@0.1.0
+```
+
+Hermes：
+
+```bash
+python -m pip install "aep-ai-connectors==0.1.0" "aep-ai-hermes==0.1.0"
+```
 
-按照[凭据签发流程](PREVIEW_CREDENTIALS_ZH.md)的最后一步创建 Scope 明确的部署 Key，
-部署新 Key，并离线保管主 Key。
+两条 Connector 路径都会注册 AEP Agent ID、映射 Runtime Identity 与 Capability
+ID、打开 Connector Session 并发送第一次 Heartbeat。精确配置以及必须执行的
+Activation 和 Discovery 验证步骤请参阅
+[Connector 接入指南](CONNECTOR_DOCS_ZH.md)。
 
 ## 获取帮助