docs: freeze cicd special-case boundaries

scripts/cli.ts

@@ -1,6 +1,6 @@
 import { readConfig } from "./src/config";
 import { debugDispatch, debugHealth, debugTask, isDebugDispatchCommand, type DebugDispatchCommand } from "./src/debug";
-import { isRebuildableService, rebuildService, stackLogs, stackStatus, startStack, stopStack } from "./src/docker";
+import { isRebuildableService, rebuildService, stackLogs, stackStatus, startStack, stopStack, unsupportedRebuildService } from "./src/docker";
 import { parseE2ERunOptions, runE2E } from "./src/e2e";
 import { emitError, emitJson } from "./src/output";
 import { jobWithTail, listJobs, listJobsSummary, readJob, runJob } from "./src/jobs";
@@ -197,7 +197,10 @@ async function main(): Promise<void> {
     }
     if (sub === "rebuild") {
       if (!isRebuildableService(third)) {
-        throw new Error("server rebuild requires one of: backend-core, frontend, dev-frontend-proxy, provider-gateway, todo-note, code-queue-mgr, project-manager, baidu-netdisk, oa-event-flow");
+        const result = unsupportedRebuildService(third);
+        emitJson(commandName, result, false);
+        process.exitCode = 1;
+        return;
       }
       emitJson(commandName, rebuildService(config, third));
       return;

scripts/src/docker.ts

@@ -27,6 +27,56 @@ export function isRebuildableService(value: string | undefined): value is Rebuil
   return rebuildableServices.some((service) => service === value);
 }
 
+export function unsupportedRebuildService(value: string | undefined): Record<string, unknown> {
+  const service = value ?? null;
+  const classifications: Record<string, Record<string, unknown>> = {
+    database: {
+      classification: "upstream-digest",
+      reason: "database uses the upstream postgres:16-alpine image and a named PGDATA volume; it is not a source-built UniDesk service",
+      replacement: "use server start/stop for lifecycle only; database image pin/mirror policy belongs to the upstream image precheck",
+      deleteAllowedLater: false,
+    },
+    filebrowser: {
+      classification: "upstream-digest",
+      reason: "filebrowser is an upstream image consumer pinned by digest/mirror policy, not a Dockerfile source-build service",
+      replacement: "future pull-only upstream digest CD; current provider-local docker-run repair remains maintenance-only",
+      deleteAllowedLater: false,
+    },
+    "filebrowser-d601": {
+      classification: "upstream-digest",
+      reason: "filebrowser-d601 is an upstream image consumer pinned by digest/mirror policy, not a Dockerfile source-build service",
+      replacement: "future pull-only upstream digest CD; current provider-local docker-run repair remains maintenance-only",
+      deleteAllowedLater: false,
+    },
+    "code-queue": {
+      classification: "standard-artifact",
+      reason: "code-queue execution plane is D601 k3s-managed and only supports the dev artifact consumer in this phase",
+      replacement: "deploy apply --env dev --service code-queue or artifact-registry deploy-service --env dev --service code-queue",
+      deleteAllowedLater: false,
+    },
+    "k3sctl-adapter": {
+      classification: "bootstrap-keep",
+      reason: "k3sctl-adapter is a D601 control bridge outside the main-server Compose stack",
+      replacement: "keep direct bridge repair and artifact plan/dry-run; live prod apply requires supervisor confirmation",
+      deleteAllowedLater: false,
+    },
+  };
+  return {
+    ok: false,
+    supported: false,
+    error: "unsupported-server-rebuild",
+    service,
+    ...(typeof value === "string" && classifications[value] !== undefined ? classifications[value] : {
+      classification: "needs-manual",
+      reason: "server rebuild can mutate only reviewed main-server Docker Compose services",
+      replacement: "inspect config.json, deploy.json, and docs/reference/cicd-standardization.md before choosing a release or maintenance path",
+      deleteAllowedLater: false,
+    }),
+    allowedServices: [...rebuildableServices],
+    policy: "server rebuild is a bootstrap/maintenance entrypoint and must not silently fall back to source builds for upstream images, D601 services, database, or unknown objects",
+  };
+}
+
 export function resolveComposeCommand(config: UniDeskConfig, envFile: string): string[] {
   const composeFile = rootPath(config.docker.composeFile);
   if (commandOk(["docker", "compose", "version"], repoRoot)) {

scripts/src/help.ts

@@ -12,7 +12,7 @@ export function rootHelp(): unknown {
       { command: "server status", description: "Show fixed ports, containers, service health, and public URLs." },
       { command: "server swap status|ensure [--path /swapfile] [--size 2GiB] [--dry-run]", description: "Inspect or idempotently create host swap for low-memory main-server operation." },
       { command: "server logs [--tail-bytes N]", description: "Return bounded tails from file logs and docker logs." },
-      { command: "server rebuild <backend-core|frontend|dev-frontend-proxy|provider-gateway|todo-note|code-queue-mgr|project-manager|baidu-netdisk|oa-event-flow>", description: "Build first, then serialize, force-recreate, and validate one Compose service." },
+      { command: "server rebuild <backend-core|frontend|dev-frontend-proxy|provider-gateway|todo-note|code-queue-mgr|project-manager|baidu-netdisk|oa-event-flow>", description: "Maintenance-only local Compose rebuild for reviewed main-server services; unsupported objects return structured errors instead of falling back to source builds." },
       { command: "provider attach <providerId> [--master-server URL] [--up] [--force]", description: "Generate the minimal external provider-gateway env/compose bundle; only master server URL and provider id are required." },
       { command: "ssh <providerId> [ssh-like args...]", description: "Open a Host SSH / WSL SSH maintenance session through the provider-gateway bridge with built-in remote helper tools in PATH." },
       { command: "ssh <providerId> apply-patch [tool args...] < patch.diff", description: "Invoke the injected remote apply_patch helper directly over SSH passthrough and stream the patch from local stdin." },
@@ -87,6 +87,12 @@ export function serverHelp(action: string | undefined = undefined): unknown {
       masterServer: "do not use server rebuild backend-core for Rust iteration; it would build locally",
       d601: "use deploy apply --env dev --service backend-core and CI for Rust build/check",
     },
+    nonRebuildableBoundary: {
+      upstreamImages: ["filebrowser", "filebrowser-d601"],
+      infrastructure: ["database", "k3sctl-adapter"],
+      d601ExecutionPlane: ["code-queue"],
+      policy: "unsupported objects return unsupported-server-rebuild and must not be coerced into main-server Compose source builds",
+    },
   };
 }