docs: clarify release manifests and runtime wiring

README.md

@@ -26,6 +26,9 @@
 - 平台 shared 之外的私有依赖必须明确来源，不能只写不存在的连接参数
 - 应用自带私有依赖的内部口令优先自动生成；外部集成凭据再向用户逐项索取
 - 只允许应用仓库 CI 向 GitOps 仓库同步当前应用自己的 release 结果与版本引用；如果当前应用的 chart 版本由 GitOps 仓库中的 `Application` 维护，则只同步更新 `apps/<app-name>/application.yaml` 里的 `targetRevision`
+- 如果运行时资源通过 `releases/<app>/manifests/` 提供，就必须同步维护这个 path 与 `Application` 中对应的 source，不能只删目录不删引用
+- 第三方镜像保持真实来源；只有当前应用 CI 实际发布的镜像才写到 `registry.baizhi.cloud/<app-name>/...`
+- 镜像内自带的 nginx / 反向代理 upstream 必须和 Chart 渲染出来的 Service 名一致，不能混用裸服务名和 fullname 前缀
 
 不适合处理：
 

gitops-app-onboarding/SKILL.md

@@ -118,6 +118,9 @@ description: 面向当前 Baizhi GitOps 平台的项目接入工作流，只适
 
 如果应用还有不适合放进 Chart 的静态清单，可以在后续发布结果中导出到当前 GitOps 仓库的 `releases/<app>/manifests/`。
 
+- 如果 Chart 运行时依赖的 `Secret`、`ConfigMap` 或 shared 资源并不是由 Chart 自己创建，而是通过 `deploy/release/secret.yaml` 或 GitOps 仓库中的 `shared/` 提供，就必须保留一个最小的 `releases/<app>/manifests/` 输出，并让当前应用的 `Application` 持续引用这个 path
+- 如果某次发布不再导出 `releases/<app>/manifests/`，就必须同时移除当前应用 `Application` 中对应的 manifests source；不要留下一个指向不存在路径的 source
+
 ## GitLab CI 规则
 
 runner 约束：
@@ -233,11 +236,15 @@ deploy/helm/<app-name>/
 - nginx 对外 Service 固定使用 `NodePort`
 - 后端 Service 默认使用集群内访问类型，不对外暴露 `NodePort`
 - 如果应用运行时依赖某个不属于平台 shared 的私有服务，Chart / release bundle 必须把该依赖的来源表达清楚：要么生成应用自带资源，要么明确引用用户已提供的外部地址；不要只留下一个指向不存在服务的 host
+- 应用自带的私有依赖如果同时需要应用口令和依赖自身启动口令，Secret key 设计要把两种消费方式都表达清楚；例如既保留 `neo4j_password` 供业务容器连接使用，也额外提供 `neo4j_auth` 这类组合值供 Neo4j 自身启动使用
 - `NodePort` 必须来自用户或平台已分配值，agent 不得自行猜测或默认分配端口
 - 不要生成 Ingress 模板或 Ingress values
 - 设置 `enableServiceLinks: false`
 - 支持 `imagePullSecrets`
 - 环境变量注入保持可读
+- 如果镜像内自带 nginx / 反向代理配置，upstream service 名必须与 Chart 实际渲染出来的 Service 名一致；如果 Chart 使用 `fullname` 前缀，就不要在镜像配置里写裸服务名 `server`、`mcp`、`frontend`
+- Kubernetes `env.value` 不会展开 `$(OTHER_ENV)` 这种 shell 变量引用；不要生成 `NEO4J_AUTH=neo4j/$(NEO4J_PASSWORD)` 这类写法并假设容器启动时会自动拼接
+- 对像 Neo4j 这类会把 `NEO4J_*` 解析为配置项的镜像，不要额外注入并不存在的配置名，例如 `NEO4J_PASSWORD`
 - 健康检查要符合真实应用行为
 
 `_helpers.tpl` 一般至少提供：
@@ -293,7 +300,8 @@ deploy/helm/<app-name>/
 
 至少应满足：
 
-- 镜像地址指向 `registry.baizhi.cloud/<app-name>/...`
+- 应用自己构建并发布的运行时镜像使用 `registry.baizhi.cloud/<app-name>/...`
+- 第三方基础镜像或官方镜像如果并未由当前应用 CI 同步到平台 registry，就保持其真实来源，不要擅自改写成 `registry.baizhi.cloud/library/...`
 - Secret 名符合平台约定
 - 私有镜像拉取时包含 `imagePullSecrets`
 - 与 Chart schema 保持一致
@@ -311,6 +319,7 @@ deploy/helm/<app-name>/
 - 先区分“外部集成凭据”和“应用自带私有依赖的内部口令”
 - 如果是外部集成凭据，应在生成到对应配置时主动向用户索取
 - 如果是应用自带私有依赖的内部口令，优先由生成流程一次性生成并写入 release secret，而不是要求用户手填
+- 如果某个工作负载需要组合型鉴权字段，例如 `username/password` 形式的单个环境变量，优先在 Secret 中直接写出完整值，再由 workload 直接读取该 key
 - 如果用户暂时没有提供，不要造占位内容冒充可部署配置
 - 对部署阻塞项，按最小必要粒度逐项提问，优先直接问“这一项应填什么”
 - 在交互会话中，如果当前步骤需要某个必填项才能继续，就先向用户索取当前顺序中的下一项
@@ -354,6 +363,7 @@ shared 边界：
 - 只要应用运行时配置仍引用某个应用私有依赖，就应在应用 Chart / release bundle 中把它一并表达出来，而不是只在 values 里保留连接参数
 - 不要把某个厂商的客户端证书、私钥、应用专属 `app_id`、tenant id、client id、namespace id、应用独有 webhook 签名密钥放进 `shared/`
 - 镜像拉取默认使用 `registry-pull-secret`，不要随便为每个应用再造一个 pull secret，除非平台模型发生变化
+- 如果 Chart 通过 `imagePullSecrets`、`platform-runtime-config`、`platform-shared-secrets` 或应用私有 release secret 引用运行时资源，而这些资源不是由 Chart 直接创建，就必须确保 `releases/<app>/manifests/` 仍然会把它们应用到目标 namespace
 
 ## 百智云用户鉴权接入
 
@@ -412,10 +422,14 @@ opensdk 读取与挂载规则：
 - 应用仓库接入文件齐全
 - `.gitlab-ci.yml` 包含 test、镜像构建、chart 发布、release 结果同步逻辑
 - release values 指向 `registry.baizhi.cloud`
+- 非当前应用自行发布的第三方镜像仍保持真实来源，不会被错误改写到平台 registry
 - GitOps 仓库更新 job 指向 `https://deploy.baizhi.cloud/gitops-admin/argodeploy.git`
 - CI 中没有直接调用 Argo
 - 仅使用 `deploy.baizhi.cloud` 与 `registry.baizhi.cloud`
 - 没有使用不安全的 HTTP registry 访问方式
+- 如果 `Application` 仍引用 `releases/<app>/manifests/`，该 path 在发布结果中实际存在且能渲染；如果发布结果不再包含该 path，`Application` 中也不会残留这个 source
+- 如果镜像内包含固定 upstream 配置，upstream service 名与当前 Chart 渲染的 Service 名保持一致，不会出现 `host not found in upstream` 这类启动错误
+- Neo4j 一类自带依赖的启动环境变量不会依赖 Kubernetes 不支持的 `$(OTHER_ENV)` 展开
 - 如果存在用户未提供的必填私有配置，交互会话会继续停在当前必填项上索取补值
 
 ## 最终输出要求