docs: 明确凭据路径与 Secret 命名

docs/api-reference.md

@@ -14,6 +14,9 @@
 
 - PostgreSQL identifier 匹配 `^[a-z][a-z0-9_]{0,62}$`。
 - 所有引用名称使用 Kubernetes DNS label/name 的相应校验。
+- Tenant 的 `spec.instanceRef` 与 `metadata.name` 长度合计不超过 241 个字符，确保派生的
+  `<instanceRef>-<metadata.name>-postgresql` 不超过 Kubernetes DNS subdomain 的
+  253 字符限制。
 - 默认值由 CRD defaulting 提供；需要读取旧值的校验由 CEL 或 webhook 完成。
 - `status` 由 controller 独占写入，禁止出现密码、Token、管理用户名或完整连接串。
 - 两个 Kind 都只承诺一个 `Ready` Condition；调用方不得依赖内部协调阶段。
@@ -68,14 +71,17 @@ namespaced，short name 为 `pgtenant`。
 | `spec.database` | string | `metadata.name` | 合法 PostgreSQL identifier |
 | `spec.loginRole` | string | `metadata.name` | database owner 兼应用 login |
 | `spec.extensions` | set[string] | 空集合 | 必须属于 Instance allowlist；成功创建后只允许追加 |
-| `spec.credential.secretName` | string | `<name>-postgresql` | 同 namespace ESO target Secret 名称 |
+| `spec.credential.secretName` | string | `<instance>-<name>-postgresql` | 合法的同 namespace ESO target Secret 名称 |
 | `spec.deletionPolicy` | enum | `Retain` | `Retain` 或 `Delete` |
 
 Tenant 不声明 OpenBao mount 或 path。controller 使用部署级 mount/base path 和
-`namespace/name` 推导稳定路径，并用 UID metadata 验证所有权。
+`namespace/name` 推导稳定路径，并用 UID metadata 验证所有权。ExternalSecret 固定为
+`<instanceRef>-<metadata.name>-postgresql`；目标 Secret 可以由用户指定，只需
+满足 Kubernetes Secret 名称校验，不限制命名内容；省略时使用相同默认名。
 
 `instanceRef`、`database`、`loginRole` 和 `credential.secretName` 在首次成功创建外部
-状态后不可变。`extensions` 只允许集合不变或追加；移除返回 `ImmutableField`，不会执行
+状态后不可变。
+`extensions` 只允许集合不变或追加；移除返回 `ImmutableField`，不会执行
 `DROP EXTENSION`。`deletionPolicy` 在对象进入删除前可以修改；删除开始后以 finalizer
 首次观察到的值为准，避免清理过程中改变授权范围。
 
@@ -163,6 +169,6 @@ spec:
   loginRole: netbox
   extensions: [pg_trgm]
   credential:
-    secretName: netbox-postgresql
+    secretName: shared-netbox-database-credentials
   deletionPolicy: Retain
 ```