docs: clarify user_key vs root_key in quickstart and basic usage

docs/en/getting-started/03-quickstart-server.md

@@ -43,15 +43,47 @@ import openviking as ov
 client = ov.SyncHTTPClient(url="http://localhost:1933")
 ```
 
-If the server has authentication enabled, pass the API key and optionally an agent ID:
+### Authentication
+
+When authentication is enabled, pass an API key. OpenViking uses a two-tier key system:
+
+**Regular data access: use a `user_key` (recommended)**
+
+For most scenarios, use a `user_key` — it directly works with tenant-scoped APIs like `add_resource`, `find`, and `ls`:
 
 ```python
 import openviking as ov
 
-client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key", agent_id="my-agent")
+client = ov.SyncHTTPClient(
+    url="http://localhost:1933",
+    api_key="<user-key>",
+    agent_id="my-agent",      # optional
+)
 ```
 
-**Full example:**
+> `user_key` is created via the Admin API (see [Authentication](../guides/04-authentication.md)). The server can automatically resolve the tenant from the key.
+
+**Administrative operations: use a `root_key`**
+
+`root_key` is for management operations (creating accounts, system status, etc.). To access tenant-scoped APIs with `root_key`, you **must** also pass `account` and `user`:
+
+```python
+import openviking as ov
+
+client = ov.SyncHTTPClient(
+    url="http://localhost:1933",
+    api_key="<root-key>",
+    account="acme",           # required: target tenant
+    user="alice",             # required: target user
+)
+```
+
+> ⚠️ Using `root_key` for `add_resource`, `find`, etc. without `account`/`user` will return:
+> `ROOT requests to tenant-scoped APIs must include X-OpenViking-Account and X-OpenViking-User headers`
+
+See [Authentication](../guides/04-authentication.md) for details (trusted mode, CLI config, etc.).
+
+**Full example (using `user_key`):**
 
 ```python
 import openviking as ov

docs/zh/getting-started/03-quickstart-server.md

@@ -43,15 +43,47 @@ import openviking as ov
 client = ov.SyncHTTPClient(url="http://localhost:1933")
 ```
 
-如果服务端启用了认证，需要传入 `api_key`，可选传入 `agent_id`：
+### 启用认证
+
+服务端启用认证后，需要传入 `api_key`。OpenViking 使用两层 API Key 体系，请根据场景选择：
+
+**常规数据访问：使用 `user_key`（推荐）**
+
+大多数场景应使用 `user_key`，可直接调用 `add_resource`、`find`、`ls` 等租户级 API：
 
 ```python
 import openviking as ov
 
-client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key", agent_id="my-agent")
+client = ov.SyncHTTPClient(
+    url="http://localhost:1933",
+    api_key="<user-key>",
+    agent_id="my-agent",      # 可选
+)
 ```
 
-**完整示例：**
+> `user_key` 通过 Admin API 创建（参见 [认证文档](../../guides/04-authentication.md)），服务端可自动识别其所属租户。
+
+**管理操作：使用 `root_key`**
+
+`root_key` 适用于管理操作（创建账户、系统状态等）。如需用 `root_key` 访问租户级 API，**必须**同时传入 `account` 和 `user`，否则服务端会拒绝请求：
+
+```python
+import openviking as ov
+
+client = ov.SyncHTTPClient(
+    url="http://localhost:1933",
+    api_key="<root-key>",
+    account="acme",           # 必须：目标租户
+    user="alice",             # 必须：目标用户
+)
+```
+
+> ⚠️ 使用 `root_key` 调用 `add_resource`、`find` 等租户级 API 时，如果未提供 `account`/`user`，会收到：
+> `ROOT requests to tenant-scoped APIs must include X-OpenViking-Account and X-OpenViking-User headers`
+
+更多认证细节（trusted 模式、CLI 配置等）请参见 [认证文档](../../guides/04-authentication.md)。
+
+**完整示例（使用 `user_key`）：**
 
 ```python
 import openviking as ov

examples/basic-usage/README.md

@@ -91,6 +91,12 @@ import openviking as ov
 client = ov.SyncHTTPClient(url="http://localhost:1933")
 ```
 
+> **Multi-tenant auth**: If the server has authentication enabled, use a `user_key` (recommended):
+> ```python
+> client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="<user-key>")
+> ```
+> A `root_key` cannot directly call tenant-scoped APIs like `add_resource` or `find` — it requires `account` and `user` parameters. See [Authentication](../../docs/en/guides/04-authentication.md) and [Server Quickstart](../../docs/en/getting-started/03-quickstart-server.md).
+
 ### Adding Resources
 
 Add URLs, local files, or directories:

examples/basic-usage/README_CN.md

@@ -91,6 +91,12 @@ import openviking as ov
 client = ov.SyncHTTPClient(url="http://localhost:1933")
 ```
 
+> **多租户认证**：如果服务端启用了认证，请使用 `user_key`（推荐）：
+> ```python
+> client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="<user-key>")
+> ```
+> `root_key` 不能直接用于 `add_resource`、`find` 等租户级 API，必须同时传入 `account` 和 `user`。详见 [认证文档](../../docs/zh/guides/04-authentication.md) 和 [快速开始：服务端模式](../../docs/zh/getting-started/03-quickstart-server.md)。
+
 ### 添加资源
 
 添加 URL、本地文件或目录：