@podosoft/podokit 0.16.3 → 0.17.0

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/server/ws-upgrade.js

@@ -0,0 +1,267 @@
+/**
+ * WebSocket upgrades, proxied by the web server itself.
+ *
+ * WHY THIS EXISTS: a SvelteKit server route cannot serve a WebSocket upgrade.
+ * `+server.ts` handlers answer HTTP requests and never see an `upgrade` event, and
+ * the `/api/*` proxy is HTTP-only for the same reason — `fetch` cannot carry a 101.
+ * Meanwhile a deployment routes all public traffic to the web app, so an API
+ * WebSocket gateway has no path to reach at all. Development hides this, because
+ * Vite proxies upgrades; the feature then dies silently once deployed.
+ *
+ * ⚠ NOTHING IS FORWARDED BY DEFAULT. `WS_PROXY_PATHS` names the exact paths that may
+ * upgrade, comma-separated, and anything else is destroyed rather than proxied. A
+ * relay that forwards any path is an open tunnel to every private route on the API,
+ * reachable from the public origin without a session. Adding a path is a security
+ * decision, not a routing tweak — the API must authorise that socket at handshake
+ * time, from the session cookie or its own credential.
+ *
+ * This file is plain JavaScript on purpose: `server.js` imports `./build/`, which
+ * only exists after a build, so the entry point cannot be type-checked. Everything
+ * with a decision in it lives here, where it is unit-tested.
+ */
+import http from "node:http";
+import https from "node:https";
+
+/** @typedef {Record<string, string | string[] | undefined>} Headers */
+/** @typedef {{ kind: "proxy", path: string } | { kind: "reject", reason: string }} UpgradeDecision */
+
+/**
+ * The upgrade paths this deployment allows, matched whole — never as a prefix, a
+ * wildcard, or a pattern.
+ *
+ * @returns {ReadonlySet<string>}
+ */
+export function relayPaths() {
+  return new Set(
+    (process.env.WS_PROXY_PATHS ?? "")
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter((entry) => entry.startsWith("/")),
+  );
+}
+
+/** Where upgrades are sent. Same target the HTTP proxy uses. */
+export function backendBaseUrl() {
+  return process.env.BACKEND_INTERNAL_URL ?? "http://localhost:5002";
+}
+
+/**
+ * Normalize a client address for the forwarded header: map loopback to a clean IPv4
+ * value and unwrap IPv4-mapped addresses.
+ *
+ * @param {string | undefined} address
+ * @returns {string | undefined}
+ */
+export function normalizeClientIp(address) {
+  if (!address) return undefined;
+  if (address === "::1" || address === "::") return "127.0.0.1";
+  if (address.startsWith("::ffff:")) return address.slice("::ffff:".length);
+  return address;
+}
+
+/**
+ * Should this upgrade be forwarded, and under which normalized path?
+ *
+ * The path is re-serialised from `URL` rather than echoed, so a target that only
+ * looks like an allowed path after resolving `..` cannot reach anything else. A
+ * request target carrying its own authority is refused outright.
+ *
+ * @param {string | undefined} url `req.url`, an origin-form request target
+ * @param {Headers} headers
+ * @param {ReadonlySet<string>} [allowed]
+ * @returns {UpgradeDecision}
+ */
+export function decideUpgrade(url, headers, allowed = relayPaths()) {
+  const upgrade = String(headers.upgrade ?? "").toLowerCase();
+  if (upgrade !== "websocket") return { kind: "reject", reason: "not a websocket upgrade" };
+  if (!url || !url.startsWith("/") || url.startsWith("//")) {
+    return { kind: "reject", reason: "not an origin-form request target" };
+  }
+  let parsed;
+  try {
+    parsed = new URL(url, "http://upgrade.invalid");
+  } catch {
+    return { kind: "reject", reason: "unparsable request target" };
+  }
+  if (!allowed.has(parsed.pathname)) return { kind: "reject", reason: "not an allowed upgrade path" };
+  return { kind: "proxy", path: `${parsed.pathname}${parsed.search}` };
+}
+
+/**
+ * What the API is told about the request.
+ *
+ * Handshake headers and the session cookie pass through untouched — the API
+ * authorises the socket from them, so dropping either turns every connection into a
+ * 401. The `x-forwarded-*` trio is appended rather than replaced: behind another
+ * proxy this server is one hop in a chain, and overwriting it reports the wrong
+ * client upstream.
+ *
+ * @param {Headers} headers
+ * @param {{ remoteAddress?: string, encrypted?: boolean }} socket
+ * @returns {Headers}
+ */
+export function upstreamHeaders(headers, socket) {
+  /** @type {Headers} */
+  const forwarded = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (value === undefined) continue;
+    if (name === "x-forwarded-for" || name === "x-forwarded-proto" || name === "x-forwarded-host") {
+      continue;
+    }
+    forwarded[name] = value;
+  }
+
+  const client = normalizeClientIp(socket.remoteAddress);
+  const chain = [headers["x-forwarded-for"], client]
+    .flat()
+    .filter((entry) => typeof entry === "string" && entry.length > 0);
+  if (chain.length > 0) forwarded["x-forwarded-for"] = chain.join(", ");
+
+  forwarded["x-forwarded-proto"] = headers["x-forwarded-proto"] ?? (socket.encrypted ? "https" : "http");
+  const host = headers["x-forwarded-host"] ?? headers.host;
+  if (host !== undefined) forwarded["x-forwarded-host"] = host;
+
+  return forwarded;
+}
+
+/**
+ * @param {string} path
+ * @param {Headers} headers
+ */
+export function upstreamOptions(path, headers) {
+  const base = new URL(backendBaseUrl());
+  return {
+    protocol: base.protocol,
+    hostname: base.hostname,
+    port: base.port || (base.protocol === "https:" ? "443" : "80"),
+    path,
+    headers,
+  };
+}
+
+/**
+ * @param {string} statusLine
+ * @param {Headers} headers
+ * @returns {string}
+ */
+function rawHead(statusLine, headers) {
+  const lines = [statusLine];
+  for (const [name, value] of Object.entries(headers)) {
+    if (value === undefined) continue;
+    if (Array.isArray(value)) for (const item of value) lines.push(`${name}: ${item}`);
+    else lines.push(`${name}: ${value}`);
+  }
+  return `${lines.join("\r\n")}\r\n\r\n`;
+}
+
+/**
+ * Streaming sockets carry many small frames, so Nagle's algorithm adds latency to
+ * every one, and the default timeout would cut an idle-but-attached connection.
+ *
+ * @param {{ setTimeout?: Function, setNoDelay?: Function, setKeepAlive?: Function }} socket
+ */
+function tune(socket) {
+  socket.setTimeout?.(0);
+  socket.setNoDelay?.(true);
+  socket.setKeepAlive?.(true, 0);
+}
+
+/** The real transport: one upstream HTTP request carrying the upgrade. */
+const nodeConnect = (options, hooks) => {
+  const transport = options.protocol === "https:" ? https : http;
+  const upstream = transport.request({
+    protocol: options.protocol,
+    hostname: options.hostname,
+    port: options.port,
+    path: options.path,
+    method: "GET",
+    headers: options.headers,
+  });
+  upstream.on("upgrade", (response, socket, head) => {
+    hooks.onUpgrade(response.statusCode ?? 101, response.headers, socket, head);
+  });
+  upstream.on("response", (response) => {
+    hooks.onResponse(response.statusCode ?? 502, response.statusMessage ?? "", response.headers);
+    response.resume(); // Drain, or the socket is never released.
+  });
+  upstream.on("error", (error) => hooks.onError(error.message));
+  upstream.end();
+  return { abort: () => upstream.destroy() };
+};
+
+/**
+ * @typedef {object} UpstreamHooks
+ * @property {(status: number, headers: Headers, socket: any, head: Uint8Array | null) => void} onUpgrade
+ * @property {(status: number, statusMessage: string, headers: Headers) => void} onResponse
+ * @property {(reason: string) => void} onError
+ */
+
+/** @typedef {(options: ReturnType<typeof upstreamOptions>, hooks: UpstreamHooks) => { abort: () => void }} Connect */
+
+/**
+ * Build the `upgrade` listener the built server mounts.
+ *
+ * The transport is injected so the decisions here are testable without a socket.
+ *
+ * @param {{ connect?: Connect, allowed?: ReadonlySet<string> }} [options]
+ */
+export function createUpgradeProxy(options = {}) {
+  const connect = options.connect ?? nodeConnect;
+  const allowed = options.allowed ?? relayPaths();
+
+  return function onUpgrade(request, socket, head) {
+    const decision = decideUpgrade(request.url, request.headers, allowed);
+    if (decision.kind === "reject") {
+      socket.destroy();
+      return;
+    }
+
+    tune(socket);
+    // Bytes the client already sent belong to the stream: push them back so the pipe
+    // below carries them upstream in order.
+    if (head && head.length > 0) socket.unshift(head);
+
+    let clientGone = false;
+    const upstream = connect(
+      upstreamOptions(decision.path, upstreamHeaders(request.headers, socket)),
+      {
+        onUpgrade(status, headers, upstreamSocket, upstreamHead) {
+          if (clientGone) {
+            upstreamSocket.destroy();
+            return;
+          }
+          if (upstreamHead && upstreamHead.length > 0) upstreamSocket.unshift(upstreamHead);
+          tune(upstreamSocket);
+          socket.write(rawHead(`HTTP/1.1 ${status} Switching Protocols`, headers));
+          // A client that hangs forever is worse than one told it lost the relay, so
+          // either end closing takes the other down.
+          upstreamSocket.on("error", () => socket.destroy());
+          upstreamSocket.on("close", () => socket.end());
+          upstreamSocket.pipe(socket);
+          socket.pipe(upstreamSocket);
+        },
+        onResponse(status, statusMessage, headers) {
+          // The API refused the handshake. Relaying ITS answer is what turns "the
+          // socket vanished" into a diagnosable failure in the browser.
+          socket.write(
+            rawHead(`HTTP/1.1 ${status} ${statusMessage}`.trim(), {
+              ...headers,
+              connection: "close",
+            }),
+          );
+          socket.end();
+        },
+        onError() {
+          socket.write(rawHead("HTTP/1.1 502 Bad Gateway", { connection: "close" }));
+          socket.end();
+        },
+      },
+    );
+
+    socket.on("error", () => upstream.abort());
+    socket.on("close", () => {
+      clientGone = true;
+      upstream.abort();
+    });
+  };
+}

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/server/ws-upgrade.test.js

@@ -0,0 +1,134 @@
+import { PassThrough } from "node:stream";
+import { describe, expect, it } from "vitest";
+import { createUpgradeProxy, decideUpgrade, upstreamHeaders } from "./ws-upgrade.js";
+
+const allowed = new Set(["/events/ws"]);
+const handshake = { upgrade: "websocket", connection: "Upgrade", host: "app.example.com" };
+
+describe("decideUpgrade", () => {
+  it("forwards an allowed path", () => {
+    expect(decideUpgrade("/events/ws", handshake, allowed)).toEqual({
+      kind: "proxy",
+      path: "/events/ws",
+    });
+  });
+
+  it("keeps the query string", () => {
+    expect(decideUpgrade("/events/ws?room=1", handshake, allowed)).toEqual({
+      kind: "proxy",
+      path: "/events/ws?room=1",
+    });
+  });
+
+  it.each([
+    ["/events/wsx", "a path that only starts the same"],
+    ["/events/ws/", "a trailing slash"],
+    ["/admin/secrets", "an unrelated path"],
+    ["/events/../admin/secrets", "traversal that resolves elsewhere"],
+    ["//evil.example.com/events/ws", "a protocol-relative target"],
+    ["http://evil.example.com/events/ws", "an absolute target"],
+  ])("rejects %s (%s)", (url) => {
+    expect(decideUpgrade(url, handshake, allowed).kind).toBe("reject");
+  });
+
+  it("rejects a request that is not a websocket upgrade", () => {
+    expect(decideUpgrade("/events/ws", { ...handshake, upgrade: "h2c" }, allowed).kind).toBe(
+      "reject",
+    );
+  });
+
+  it("forwards nothing when no path is configured", () => {
+    expect(decideUpgrade("/events/ws", handshake, new Set()).kind).toBe("reject");
+  });
+});
+
+describe("upstreamHeaders", () => {
+  it("passes the handshake and cookie through", () => {
+    const headers = upstreamHeaders(
+      { ...handshake, cookie: "session=abc", "sec-websocket-key": "k" },
+      {},
+    );
+    expect(headers.cookie).toBe("session=abc");
+    expect(headers["sec-websocket-key"]).toBe("k");
+    expect(headers.upgrade).toBe("websocket");
+  });
+
+  it("appends to an existing forwarded chain rather than replacing it", () => {
+    const headers = upstreamHeaders(
+      { ...handshake, "x-forwarded-for": "203.0.113.7" },
+      { remoteAddress: "::ffff:10.0.0.2" },
+    );
+    expect(headers["x-forwarded-for"]).toBe("203.0.113.7, 10.0.0.2");
+  });
+
+  it("reports the scheme the client actually used", () => {
+    expect(upstreamHeaders(handshake, { encrypted: true })["x-forwarded-proto"]).toBe("https");
+    expect(upstreamHeaders(handshake, {})["x-forwarded-proto"]).toBe("http");
+  });
+});
+
+describe("createUpgradeProxy", () => {
+  function socket() {
+    const stream = new PassThrough();
+    stream.destroy = () => {
+      stream.destroyed = true;
+      return stream;
+    };
+    return stream;
+  }
+
+  it("destroys a rejected upgrade without contacting the API", () => {
+    let called = false;
+    const proxy = createUpgradeProxy({ allowed, connect: () => ((called = true), { abort() {} }) });
+    const client = socket();
+    proxy({ url: "/admin/secrets", headers: handshake }, client, null);
+    expect(called).toBe(false);
+    expect(client.destroyed).toBe(true);
+  });
+
+  it("relays the API's refusal instead of dropping the socket", () => {
+    const proxy = createUpgradeProxy({
+      allowed,
+      connect: (_options, hooks) => {
+        hooks.onResponse(401, "Unauthorized", { "content-length": "0" });
+        return { abort() {} };
+      },
+    });
+    const client = socket();
+    /** @type {string[]} */
+    const written = [];
+    client.on("data", (chunk) => written.push(chunk.toString()));
+    proxy({ url: "/events/ws", headers: handshake }, client, null);
+    expect(written.join("")).toContain("HTTP/1.1 401 Unauthorized");
+  });
+
+  it("answers 502 when the API cannot be reached", () => {
+    const proxy = createUpgradeProxy({
+      allowed,
+      connect: (_options, hooks) => (hooks.onError("ECONNREFUSED"), { abort() {} }),
+    });
+    const client = socket();
+    /** @type {string[]} */
+    const written = [];
+    client.on("data", (chunk) => written.push(chunk.toString()));
+    proxy({ url: "/events/ws", headers: handshake }, client, null);
+    expect(written.join("")).toContain("HTTP/1.1 502 Bad Gateway");
+  });
+
+  it("writes the 101 and pipes both directions once upstream upgrades", () => {
+    const upstream = socket();
+    const proxy = createUpgradeProxy({
+      allowed,
+      connect: (_options, hooks) => {
+        hooks.onUpgrade(101, { upgrade: "websocket" }, upstream, null);
+        return { abort() {} };
+      },
+    });
+    const client = socket();
+    /** @type {string[]} */
+    const written = [];
+    client.on("data", (chunk) => written.push(chunk.toString()));
+    proxy({ url: "/events/ws", headers: handshake }, client, null);
+    expect(written.join("")).toContain("HTTP/1.1 101 Switching Protocols");
+  });
+});

package/dist/templates/fullstack-nest-svelte/apps/web/src/routes/api/[...path]/+server.ts

@@ -1,9 +1,13 @@
 import type { RequestHandler } from "@sveltejs/kit";
-import { backendBaseUrl, proxyRequest } from "$lib/server/backend-proxy";
+import { backendBaseUrl, proxyRequest, resolveClientIp } from "$lib/server/backend-proxy";
 
 // Proxy the app's REST API, stripping the /api prefix (backend routes are at root).
 const handler: RequestHandler = ({ request, params, url, getClientAddress }) =>
-  proxyRequest(request, `${backendBaseUrl()}/${params.path}${url.search}`, getClientAddress());
+  proxyRequest(
+    request,
+    `${backendBaseUrl()}/${params.path}${url.search}`,
+    resolveClientIp(getClientAddress),
+  );
 
 export const GET = handler;
 export const POST = handler;

package/dist/templates/fullstack-nest-svelte/apps/web/src/routes/api/auth/[...all]/+server.ts

@@ -1,9 +1,13 @@
 import type { RequestHandler } from "@sveltejs/kit";
-import { backendBaseUrl, proxyRequest } from "$lib/server/backend-proxy";
+import { backendBaseUrl, proxyRequest, resolveClientIp } from "$lib/server/backend-proxy";
 
 // Proxy the better-auth handler, keeping the /api/auth prefix.
 const handler: RequestHandler = ({ request, params, url, getClientAddress }) =>
-  proxyRequest(request, `${backendBaseUrl()}/api/auth/${params.all}${url.search}`, getClientAddress());
+  proxyRequest(
+    request,
+    `${backendBaseUrl()}/api/auth/${params.all}${url.search}`,
+    resolveClientIp(getClientAddress),
+  );
 
 export const GET = handler;
 export const POST = handler;

package/dist/templates/fullstack-nest-svelte/apps/web/vite.config.ts

@@ -7,13 +7,23 @@ import { defineConfig } from "vite";
 // browser origin so the same configuration works for both entry points.
 const inDocker = process.env.VITE_DOCKER === "1";
 
+// Dev parity for WebSocket upgrades. In production `server.js` proxies these paths to
+// the API; without the same allowlist here, a feature would work in one and not the
+// other -- which is exactly how a WebSocket gateway used to reach production dead.
+// Set WS_PROXY_PATHS in the shell that runs vite; a .env file cannot reach this file.
+const wsProxyPaths = (process.env.WS_PROXY_PATHS ?? "")
+  .split(",")
+  .map((entry) => entry.trim())
+  .filter((entry) => entry.startsWith("/"));
+const backendTarget = process.env.BACKEND_INTERNAL_URL ?? "http://localhost:5002";
+const wsProxy = Object.fromEntries(
+  wsProxyPaths.map((path) => [path, { target: backendTarget, ws: true, changeOrigin: false }]),
+);
+
 export default defineConfig({
   plugins: [tailwindcss(), sveltekit()],
-  server: inDocker
-    ? {
-        host: true,
-        port: 5001,
-        allowedHosts: true,
-      }
-    : undefined,
+  server: {
+    ...(inDocker ? { host: true, port: 5001, allowedHosts: true } : {}),
+    ...(wsProxyPaths.length ? { proxy: wsProxy } : {}),
+  },
 });

package/dist/templates/fullstack-nest-svelte/dot-agents/skills/podokit-deploy/SKILL.md

@@ -1,20 +1,65 @@
 ---
 name: podokit-deploy
-description: Plan, inspect, apply, verify, and roll back PodoKit Kubernetes releases with an explicit deployment profile and confirmation hash. Use when an agent needs to initialize a .podokit/deploy profile, diagnose a target cluster, preview a release, perform an approved deployment, inspect rollout state, verify public endpoints, or prepare an application rollback.
+description: Plan, inspect, apply, verify, and roll back PodoKit releases with an explicit deployment profile and confirmation hash, on Kubernetes or Docker Compose. Use when an agent needs to initialize a .podokit/deploy profile, diagnose a target, preview a release, perform an approved deployment, inspect rollout state, verify public endpoints, or prepare a rollback.
 ---
 
 # Deploy a PodoKit application
 
+A profile records which driver it uses, so every command below is the same for both.
+Read the profile's `driver` first and say which one you are operating.
+
+| Driver | Target | Use it when |
+| --- | --- | --- |
+| `kubernetes-helm` | a cluster context and namespace | you already run a cluster, or you need more than one node, cluster-managed rollouts, or per-workload scaling |
+| `docker-compose` | one Docker host, local or over `ssh://` | one machine is the whole deployment and a reverse proxy in front of it terminates TLS |
+
 1. Run `npx @podosoft/podokit status`, `npx @podosoft/podokit diff`, and `npx @podosoft/podokit doctor`. Stop if managed-file conflicts or unsupported framework versions could make the image unreliable.
 2. Read [references/profile.md](references/profile.md) before creating or changing a deployment profile.
-3. Run `npx @podosoft/podokit deploy doctor --profile <name>`. Resolve every failure without printing Secret values.
-4. Run `npx @podosoft/podokit deploy plan --profile <name> --release <stable-semver> --json`.
-5. Show the user the context, cluster fingerprint result, namespace, Helm release, exact images, current revision and status, actions, migration warning, and plan hash.
-6. Do not apply until the user explicitly approves that exact plan.
-7. Apply with `npx @podosoft/podokit deploy apply --profile <name> --release <stable-semver> --confirm <plan-hash>`.
-8. Run `npx @podosoft/podokit deploy status --profile <name> --json` and `npx @podosoft/podokit deploy verify --profile <name> --json`.
-9. Report the exact images, Helm revision, ready replicas, restart totals, and verification result.
+3. Make sure the images exist for that tag. Read [references/release.md](references/release.md): tagging `vX.Y.Z` runs the release workflow, which builds and pushes both images and stops there. Never apply a release whose images were not published.
+4. Run `npx @podosoft/podokit deploy doctor --profile <name>`. Resolve every failure without printing secret values.
+5. Run `npx @podosoft/podokit deploy plan --profile <name> --release <stable-semver> --json`.
+6. Show the user the driver, the target (context plus namespace and Helm release, or Docker context plus Compose project), the fingerprint result, the exact image digests, the current revision, the actions, the migration warning, and the plan hash.
+7. Do not apply until the user explicitly approves that exact plan.
+8. Apply with `npx @podosoft/podokit deploy apply --profile <name> --release <stable-semver> --confirm <plan-hash>`.
+9. Run `npx @podosoft/podokit deploy status --profile <name> --json` and `npx @podosoft/podokit deploy verify --profile <name> --json`.
+10. Report the exact images, the revision, running replicas, restart totals, and the verification result. Report `syncDrift` too: a non-empty value means containers are running locally synced artifacts and the release tag does not describe what is serving.
+
+## Iterating against a deployment is a different command
+
+If the user is changing code and wants to see it on the deployment, a release is the
+wrong loop — it rebuilds and republishes to move a few megabytes of compiled output.
+Use the `podokit-deploy-fast` skill (`podo deploy sync`, docker-compose driver only).
+Reach for a release when the change needs a migration, changes runtime dependencies,
+or is going to real users.
+
+## The migration runs against the release that is still serving
+
+Both drivers run the migration **before** the new containers start, and both keep the
+previous release serving while the new one rolls out. So a migration must be
+compatible with the code already running:
+
+- Additive changes are safe: new tables, new nullable columns, new indexes.
+- Dropping or renaming a column, or tightening a constraint, breaks the running
+  release the moment the migration commits — before any new code is live.
+- Destructive changes belong in a **second** release, after the code that stopped
+  using the column has fully rolled out.
+
+Rollback does not reverse migrations on either driver. If an older image cannot read
+the current schema, roll forward instead.
+
+## Rollback
+
+Read [references/rollback.md](references/rollback.md), preview the target revision
+without `--confirm`, show the new plan hash, and obtain explicit approval.
+
+The compose driver can only reproduce a revision whose rendered project still matches
+the current profile byte for byte; if the profile changed since, it refuses and tells
+you to roll forward.
 
-For rollback, read [references/rollback.md](references/rollback.md), preview the target revision without `--confirm`, show the new plan hash, and obtain explicit approval.
+## Boundary
 
-Never create or rotate cluster credentials, registry credentials, DNS, virtual machines, Kubernetes Secrets, or backup repositories. Never put a password, token, private key, connection URL containing credentials, or Secret value in a profile, command argument, log, or report.
+Never create or rotate cluster credentials, registry credentials, DNS records,
+virtual machines, Kubernetes Secrets, env files on a deployment host, TLS
+certificates, or backup repositories. Never put a password, token, private key,
+connection URL containing credentials, or secret value in a profile, a command
+argument, a log, or a report.

package/dist/templates/fullstack-nest-svelte/dot-agents/skills/podokit-deploy/references/profile.md

@@ -1,6 +1,10 @@
 # Deployment profile
 
-The profile at `.podokit/deploy/<name>.json` is application-owned and contains no Secret values.
+The profile at `.podokit/deploy/<name>.json` is application-owned and contains no
+secret values. It declares a `driver`, and that decides the shape of the rest of the
+document.
+
+## kubernetes-helm (default)
 
 Initialize it with an explicit kubeconfig context:
 
@@ -35,3 +39,48 @@ Required keys:
 Use `inCluster` when the generated Helm release should manage a dependency, `external` when application configuration points to an existing service, and `disabled` only when the application does not require it.
 
 Use the same stable SemVer tag for API and web. `latest`, branch tags, and empty tags are rejected. Planning resolves every deployed tag to an immutable registry digest through Docker Buildx.
+
+## docker-compose
+
+Initialize it with an explicit Docker context. The context may be local or `ssh://`,
+and it is pinned by a fingerprint of the endpoint plus the daemon ID, so repointing
+it at a different host invalidates the profile instead of deploying somewhere else.
+
+```bash
+npx @podosoft/podokit deploy init \
+  --profile production \
+  --driver docker-compose \
+  --context production \
+  --host app.example.com \
+  --secrets-dir /etc/podokit/example-app
+```
+
+The fields that differ from the Kubernetes driver:
+
+- `target`: Docker context, endpoint fingerprint, Compose project name
+- `exposure`: `bindAddress` and `port` published from the web service. It defaults to
+  `127.0.0.1`, because the expected front door is a reverse proxy on the same host —
+  binding every interface publishes the app before TLS exists
+- `workloads`: replicas plus Compose `cpus` and `memory` limits
+- `dependencies`: `managed`, `external`, or `disabled`, each with a named Docker
+  volume and the path of its env file on the target host
+- `secrets`: env-file paths and required key names, plus `registryLogin`
+
+Credentials live in env files **on the target host**, never in the profile and never
+in the rendered Compose project. The doctor reads only the key names, in a throwaway
+container that mounts the file read-only. Create those files with the host's own
+secret tooling before deploying; PodoKit does not write them.
+
+Required keys:
+
+| Env file | Required keys |
+| --- | --- |
+| API | Profile-declared keys plus enabled dependency connection keys: `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, `REDIS_PASSWORD`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` |
+| web | Only explicitly declared web keys; omitted by default |
+| PostgreSQL dependency | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` |
+| Redis dependency | `REDIS_PASSWORD` |
+| Object storage dependency | `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` |
+
+Data volumes are declared `external`, so `docker compose down -v` cannot delete the
+database. Editing an env file changes the containers' rollout label, so the next
+apply actually restarts them instead of leaving stale environment values running.

package/dist/templates/fullstack-nest-svelte/dot-agents/skills/podokit-deploy/references/release.md

@@ -0,0 +1,64 @@
+# Publishing the images a release deploys
+
+`podo deploy` consumes images. Building them is `.github/workflows/release.yml`,
+which triggers on a `v*.*.*` tag, verifies the commit, builds both images from the
+repository root, and pushes them under that one tag. It does not roll out.
+
+```bash
+git tag v1.2.3
+git push origin v1.2.3
+```
+
+Then plan and apply as the main skill describes. `podo deploy plan` resolves the tag
+to an immutable digest, so a tag whose images were never pushed fails there rather
+than half way through a rollout.
+
+## Before the first tag: check the runner
+
+**GitHub-hosted runners are free for public repositories only.** In a private
+repository every minute is metered against the account's included Actions minutes and
+billed beyond them, and image builds are usually the most expensive job a project
+runs. A self-hosted runner consumes no Actions minutes at all.
+
+The workflow reads the choice from a variable, so it is a setting rather than an edit:
+
+| Variable | Unset | Notes |
+| --- | --- | --- |
+| `PODOKIT_RUNNER` | `["ubuntu-latest"]` | JSON array of labels. Self-hosted example: `["self-hosted","Linux","X64"]` |
+| `PODOKIT_DEPLOY_PROFILE` | `production` | which `.podokit/deploy/<name>.json` names the image repositories |
+| `PODOKIT_IMAGE_PLATFORM` | `linux/amd64` | the architecture the **deployment target** runs, not the runner's |
+
+Nothing warns when a private repository is still on the default: the workflow
+succeeds either way and the difference appears on a bill. **When asked to set up
+releases, check the repository's visibility first and say which case it is.**
+
+`PODOKIT_IMAGE_PLATFORM` is the other one worth stating out loud. Building for the
+wrong architecture produces `exec format error` at rollout — after the migration has
+already run — and building for the right one on a runner of a different architecture
+works but runs under emulation, which is slow enough to be mistaken for a problem
+with Docker.
+
+## Secrets
+
+`REGISTRY_USERNAME` and `REGISTRY_PASSWORD`, for the registry named by the profile's
+`release.apiRepository`. A robot or deploy account is enough for pushing, but some
+registries do not let a robot **create** a repository — push the first tag of a new
+repository with an account that can, or create the repository in the registry first.
+
+Never print either value, and never put one in a profile, a command argument, or a
+report.
+
+## Building by hand
+
+Only when a tag is not the right trigger. Build for the target's architecture, tag
+both images identically, and push before planning:
+
+```bash
+docker build --platform linux/amd64 -f apps/api/Dockerfile -t <api-repository>:v1.2.3 .
+docker build --platform linux/amd64 -f apps/web/Dockerfile -t <web-repository>:v1.2.3 .
+docker push <api-repository>:v1.2.3
+docker push <web-repository>:v1.2.3
+```
+
+A bare local tag cannot be deployed: it does not match the profile's stable SemVer
+pattern and cannot be resolved to a digest.