docs: capture langbot platform infra rules

.agents/skills/unidesk-ops/SKILL.md

@@ -155,9 +155,11 @@ bun scripts/cli.ts platform-db postgres apply --config config/platform-db/postgr
 
 - `plan` / `status` 只读；`apply --confirm` 默认创建本地异步 job；`apply --confirm --wait` 会启动 PK01 侧 root-owned job 并短轮询。
 - 输出只显示 Secret key 名、presence、fingerprint、连接 host、SSL 状态和状态摘要；禁止打印密码或完整 `DATABASE_URL`。
+- 同一个 PK01 PostgreSQL 实例可承载多个 YAML 声明的 role/database；新增消费者按 `secrets.entries`、`objects.roles`、`objects.databases`、`postgres.auth.pgHba` 和 `exports.connectionStrings` 成套声明，不新开 PostgreSQL 实例，也不默认用 schema 隔离应用状态。
 - 跨节点消费者必须直连 YAML 的 `postgres.network.connectionHost`，当前是 PK01 公网 endpoint；不要让 D601/G14/Sub2API/HWLAB/AgentRun 通过 master server 中转 PostgreSQL。
 - 当前 TLS 口径是 PostgreSQL native TLS + `sslmode=require`。`publicDns` 只是可选 alias；只要 `connectionHost` 是可达 IP，DNS 未解析不作为切库 blocker。
 - 远端 PostgreSQL 配置或 `pg_hba` 来源 CIDR 变化后，先跑 `apply --confirm --wait`，再跑 `status`；若消费者公网出口 IP 变化，必须先更新 YAML `allowSources` 和对应 `pg_hba`。
+- `status` 验收要看 `roles[]`、`databases[]` 和 `appConnections[]`；不要只看旧的 `roleExists` / `databaseExists` 标量。
 
 日常复验建议：
 

docs/reference/g14.md

@@ -217,6 +217,7 @@ The G14 host persists this proxy configuration in these local files:
 - `/root/.gitconfig` pins root Git HTTP/HTTPS proxy settings.
 - `/root/.docker/config.json` pins Docker client proxy settings for commands and build contexts that honor Docker client proxy configuration.
 - `/etc/systemd/system/docker.service.d/proxy.conf` pins Docker daemon pull proxy settings. Updating this drop-in requires `systemctl daemon-reload` and a Docker restart before the active daemon sees the new `NO_PROXY`; do not restart Docker while G14 provider-gateway, k3s bootstrap or image builds are in flight unless that interruption is intentional.
+- `/etc/systemd/system/k3s.service.env` pins k3s/containerd image-pull proxy settings. If Pod events show image pulls failing through a stale loopback proxy such as `127.0.0.1:10808` while Hysteria is the active listener, update this file through `trans G14:/etc/systemd/system apply-patch`, run `systemctl daemon-reload`, restart k3s, then verify node readiness and the target image pull. Do not hand-import images as the long-term fix for a stale k3s proxy env.
 
 The `NO_PROXY` list must include localhost, the main server, private LAN ranges, k3s pod/service CIDRs, Kubernetes service domains and the loopback registry so that k3s, `127.0.0.1:5000`, Kubernetes API access and UniDesk control paths do not route through the VPN proxy.
 
@@ -237,7 +238,7 @@ docker build --network host \
 
 The backup proxy uses `HTTP_PROXY=http://127.0.0.1:11809`, `HTTPS_PROXY=http://127.0.0.1:11809` and `ALL_PROXY=socks5h://127.0.0.1:11808`.
 
-This proxy is not a replacement for UniDesk runtime egress. k3s workloads such as Code Queue must still use the cataloged `g14-provider-egress-proxy` Kubernetes Service and `g14-tcp-egress-gateway` for normal runtime access to PostgreSQL, OA Event Flow and external APIs. The node-local VPN proxy is allowed only for G14 host-side bootstrap, image build, cache prewarm or recovery steps, and those steps should record the proxy choice in issue or deployment evidence.
+This proxy is not a replacement for UniDesk runtime egress. k3s workloads such as Code Queue must still use the cataloged `g14-provider-egress-proxy` Kubernetes Service and `g14-tcp-egress-gateway` for normal runtime access to PostgreSQL, OA Event Flow and external APIs. The node-local VPN proxy is allowed only for G14 host-side bootstrap, k3s image pulls, image build, cache prewarm or recovery steps, and those steps should record the proxy choice in issue or deployment evidence.
 
 Runtime egress readiness is not proven by Service DNS alone. Before closing HWLAB, AgentRun, Code Queue, CI/CD or user-service issues that require GitHub/codeload/npm/pip/API access through `g14-provider-egress-proxy`, validate that the Deployment is Ready and the Service has at least one ready endpoint. If the Service resolves but `curl` through `http://g14-provider-egress-proxy.unidesk.svc.cluster.local:18789` fails immediately with connection refused, inspect `unidesk/g14-provider-egress-proxy` and `unidesk/g14-tcp-egress-gateway` pods for `ImagePullBackOff`, `ContainerStatusUnknown` or notReady endpoints. A pod trying to pull `unidesk-code-queue:g14` from Docker Hub as `docker.io/library/unidesk-code-queue:g14` is an invalid runtime egress deployment state; restore the controlled image source/import path instead of redirecting long-lived workload proxy env to the node-local bootstrap proxy.
 

docs/reference/pk01.md

@@ -72,11 +72,15 @@ The public certificate depends on DNS. The `api.pikapython.com` record must reso
 
 PK01 host-native PostgreSQL is declared by `config/platform-db/postgres-pk01.yaml` and managed through `bun scripts/cli.ts platform-db postgres plan|status|apply`; daily operation commands live in `$unidesk-ops` at `.agents/skills/unidesk-ops/SKILL.md`. It is a host systemd service, not a Docker container or k3s workload. The YAML is the source of truth for PostgreSQL version, TLS mode, listening addresses, `pg_hba` source CIDRs, generated Secret source files, exported `DATABASE_URL`, and backup timer settings.
 
+The PK01 PostgreSQL cluster is a shared platform database instance. Multiple UniDesk services may be declared as separate `objects.roles[]` and `objects.databases[]` entries, with matching Secret sources, `pg_hba` hostssl rules and optional connection-string exports. A new platform consumer should use its own database and role inside this existing instance; do not create a second PostgreSQL instance or use one database with multiple schemas as the default isolation boundary for application state.
+
 Cross-node platform consumers must connect directly to the YAML-declared `postgres.network.connectionHost`. For consumers outside the PK01 private VPC, that value must be PK01's public endpoint, not the private `10.0.8.3` address and not a master-server tunnel. The master server may run control-plane CLI operations and secret sync, but it must not become the data-plane relay for D601, G14, Sub2API, HWLAB, AgentRun, or other PostgreSQL clients.
 
 `postgres.network.publicDns` is an optional alias for operator readability and future `sslmode=verify-full` work. With the current PostgreSQL native TLS posture, clients use `sslmode=require`; DNS resolution is therefore not a cutover blocker when `connectionHost` is a reachable IP endpoint. If `publicDns` later becomes the connection host or `verify-full` is enabled, certificate common name/SAN and DNS must be promoted back into the cutover criteria.
 
-The exported Sub2API connection string is written under the configured ignored Secret root and must never be committed or printed in full. CLI output may show key names, presence, fingerprints, selected host, SSL status, and source/target Secret references only. If a consumer's public egress IP changes, update the YAML `allowSources` and matching `pg_hba` rules, then use the `$unidesk-ops` PK01 Host PostgreSQL workflow to apply and recheck status.
+Exported connection strings are written under the configured ignored Secret root and must never be committed or printed in full. CLI output may show key names, presence, fingerprints, selected host, SSL status, app connection status, and source/target Secret references only. If a consumer's public egress IP changes, update the YAML `allowSources` and matching `pg_hba` rules, then use the `$unidesk-ops` PK01 Host PostgreSQL workflow to apply and recheck status.
+
+Backup coverage is explicit YAML state. Do not assume every declared database is backed up unless the backup configuration names it directly or the CLI reports multi-database coverage.
 
 ## Disk GC Policy
 

docs/reference/platform-infra.md

@@ -29,8 +29,12 @@
 - LangBot uses the existing PK01 host-native PostgreSQL instance through `config/platform-db/postgres-pk01.yaml` and `platform-db postgres`. Adding LangBot state means adding a dedicated database and role inside that existing instance; do not deploy a second PostgreSQL StatefulSet, container, or external DB instance for LangBot.
 - Public exposure uses PK01 Caddy plus FRP to the G14 ClusterIP service. Do not add Kubernetes Ingress, NodePort, LoadBalancer, host networking, or host ports for LangBot unless a later YAML-controlled platform decision changes the exposure model.
 - LangBot's built-in Web frontend and API share the same public HTTPS origin. CLI queries must use the YAML-declared API key source and must report key names/fingerprints only, never the API key value.
+- `bootstrap-api-key` writes the YAML-declared key into LangBot's `api_keys` table after the app has initialized its schema. If the table is absent, start LangBot first and let its migrations run; do not create a parallel auth table or print the key while seeding it.
+- LangBot startup logs may include upstream env override values. `platform-infra langbot logs` must redact env keys containing `PASSWORD`, `SECRET`, `TOKEN`, `API_KEY`, or `DATABASE_URL`; any leaked DB password, JWT secret, or API key must be rotated through YAML/Secret sources and rolled out through the controlled `apply` path.
+- LangBot Secret material changes must update the app Deployment template with a Secret fingerprint annotation so `apply` rolls the Pod. Manual Pod deletion is only a temporary recovery action, not the durable rotation mechanism.
+- Closeout for public LangBot changes requires `platform-infra langbot status`, `platform-infra langbot validate`, and an API-key-backed `platform-infra langbot query`; frontend exposure is proved by the same public origin returning the built-in Web UI.
 - LangBot Box is disabled by default for the public service because the official Box deployment needs Docker socket access. Enabling Box requires a separate explicit platform decision and YAML-controlled security boundary.
-- Official WeChat support is through LangBot's official platform adapters such as `officialaccount`, `wecom`, and `wecomcs`. Personal WeChat or OpenClaw-style adapters are not part of the default public-service boundary.
+- Official WeChat support is through LangBot's official platform adapters such as `officialaccount`, `wecom`, and `wecomcs`; real AppID, token, EncodingAESKey and channel credentials are bound in LangBot after deployment. Personal WeChat or OpenClaw-style adapters are not part of the default public-service boundary.
 
 ## Codex Pool Routing