docs: document shared PK01 Caddy blocks

docs/reference/pk01.md

@@ -58,9 +58,13 @@ PK01 currently hosts existing Docker workloads:
 
 `pikanode` mounts `/home/ubuntu/pikanode` read-write into the container. Static/generated download artifacts under `html/download/` and repository data under `files/` may be user-visible or needed by the service. They are not generic GC candidates.
 
-## Sub2API Caddy Edge
+## Shared Caddy Edge
 
-PK01 may act as the public Caddy edge for a YAML-declared D601 Sub2API target. The durable source of truth is `config/platform-infra/sub2api.yaml`; do not hand-edit PK01 Caddy or FRP state as a separate routing truth.
+PK01 may act as the public Caddy edge for several YAML-declared UniDesk services. The durable source of truth stays in the owning YAML, such as `config/platform-infra/sub2api.yaml`, `config/platform-infra/langbot.yaml`, `config/platform-infra/n8n.yaml`, and the HWLAB node/lane YAML. Do not hand-edit PK01 Caddy or FRP state as a separate routing truth.
+
+`/etc/caddy/Caddyfile` is a shared artifact. UniDesk-managed writers must update only their own `# BEGIN unidesk managed <owner>` block, preserve other managed blocks, validate the merged file with Caddy before install, and reload Caddy only after validation succeeds. The shared helper is `scripts/src/pk01-caddy.ts`; service CLIs should call it through their owning public-exposure wrapper instead of carrying a private full-file Caddy writer.
+
+If one public service fails while other services still work, restore the missing route through that service's YAML-controlled apply/public-exposure command, not by replacing the whole Caddyfile. A diagnostic check may list managed block markers with `grep '^# BEGIN unidesk managed ' /etc/caddy/Caddyfile` and run `sudo caddy validate --config /etc/caddy/Caddyfile`, but those checks are evidence only; durable repair belongs to the owning CLI.
 
 In this mode, public ports `80` and `443` belong to Caddy. The existing `pikanode` container must be bound to a loopback HTTP port and used only as the apex PikaPython/PikaNode upstream. The `api.pikapython.com` site must reverse proxy directly to the YAML-declared FRP remote port, so API traffic follows `client -> PK01 Caddy -> PK01 frps remote port -> D601 frpc -> D601 Sub2API`. It must not pass through pikanode or a master-server reverse proxy.
 

docs/reference/platform-infra.md

@@ -173,6 +173,10 @@ The public management UI is an operations endpoint. Keep Sub2API itself in `plat
 
 The public bridge has two separate failure classes. Sub2API upstream/account failures are visible in Sub2API logs and currently belong to sentinel quarantine plus normal Sub2API routing among schedulable accounts. Edge failures between Caddy and the FRP remote port are not visible to Sub2API; symptoms include Caddy `connect: connection refused`, EOF, connection reset, TLS/certificate failures, DNS NXDOMAIN, or short 502 bursts while frps closes and reopens the configured remote port. Those failures must be diagnosed from DNS, Caddy, and frps/frpc evidence and mitigated through YAML-controlled Caddy edge retry, DNS correction, or FRP stability fixes, not by disabling accounts or changing pool membership.
 
+PK01 `/etc/caddy/Caddyfile` is a shared edge artifact for multiple YAML owners, including platform-infra services and HWLAB node public exposure. Every platform-infra writer must use the shared managed-block helper in `scripts/src/pk01-caddy.ts` or the platform public-service wrapper around it. The helper preserves existing UniDesk managed blocks, updates only the caller's marker block, validates the merged Caddyfile before install, and reloads Caddy only after validation succeeds.
+
+Do not render and install a whole PK01 Caddyfile from a single service YAML. Sub2API, LangBot, n8n, HWLAB and future public services must coexist by distinct `# BEGIN unidesk managed <owner>` blocks. A public exposure closeout should verify the service's own public URL and, when the operation touched PK01 Caddy, confirm that unrelated managed blocks are still present or that the apply output reports they were preserved.
+
 ## Availability And Probes
 
 Kubernetes readiness is not the same as pool availability:

docs/reference/yaml-first-ops.md

@@ -91,6 +91,10 @@ App-specific transforms are allowed only as isolated named transform functions.
 
 Public exposure must be declared as an edge topology, including DNS expectation, public base URL, bridge settings, edge host route and target service. The existing FRP/Caddy path is a reusable public-service primitive. New public exposure code should extend that primitive instead of adding per-service Caddy or FRP scripts.
 
+When several YAML owners render into the same Caddyfile, each owner must write only its own managed site block and merge it with the existing file. A shared writer must preserve other `# BEGIN unidesk managed <owner>` blocks, remove only legacy unmanaged blocks for the domains owned by the current operation, validate the merged Caddyfile before install, and then reload Caddy. A domain CLI must not replace a shared Caddyfile with a file rendered from its own YAML alone.
+
+Shared Caddyfile operations belong in a common helper module under `scripts/src/`. Service-specific CLIs should pass YAML-resolved domains, upstreams and marker names to that helper, then report the managed-block counts and validation result. Full-file Caddy installs are allowed only for a host or file that the command exclusively owns and whose exclusivity is documented in the owning reference.
+
 ### Database Blocks
 
 External database consumers must reference the YAML-owned platform database source and exported Secret shape. A consumer should not deploy a new database, copy connection strings by hand, or derive credentials from live runtime objects unless the owning database YAML declares that export.
@@ -122,6 +126,7 @@ Avoid these patterns:
 - hard-coding node ids, service ids, namespaces, ports, URLs, Secret names or workload names in code
 - deriving live state by string conventions when YAML can declare the object directly
 - keeping repeated `kubectl apply`, Caddy edits, FRP edits or rollout restarts as runbook shell snippets
+- replacing a shared Caddyfile from one YAML owner without preserving other managed blocks
 - printing secret values, complete env files, full `DATABASE_URL` values or reusable API keys
 - writing long-term docs that duplicate current YAML values as prose
 - using contract tests or hidden guards to freeze policy values that should remain YAML-controlled