@podosoft/podokit 0.16.3 → 0.17.0

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

@@ -0,0 +1,92 @@
+---
+name: podokit-deploy-fast
+description: Push locally built artifacts into a running Docker Compose deployment and restart it, without building or publishing an image. Use when iterating on code against a deployed environment and a full release round trip is too slow. Not for releases, migrations, dependency changes, or anything going to real users.
+---
+
+# Sync code into a running deployment
+
+`podo deploy sync` copies this project's build output into the containers that are
+already running and restarts them. `docker-compose` driver only — read the profile's
+`driver` first and stop if it is `kubernetes-helm`, where the equivalent would have
+to reach every node and would stop being a shortcut.
+
+```bash
+npx @podosoft/podokit deploy sync --profile <name> --build
+```
+
+## Say what this does before doing it
+
+It is not a release, and the user has to understand three consequences before you run
+it:
+
+1. **The deployment will run code its image tag does not describe.** A marker file
+   records the sync and `podo deploy status` reports it under `syncDrift`.
+2. **Every connection the restarted containers hold is dropped** — WebSocket sessions,
+   in-flight requests, anything attached.
+3. **It disappears on the next release.** Container writable layers do not survive
+   recreation, so `podo deploy apply` restores the image with no cleanup step. That is
+   the property that makes this safe; do not build anything that depends on the copy
+   persisting.
+
+## When NOT to use it
+
+Use a release instead — build the images and `podo deploy apply` — when any of these
+is true. The first three are refusals the command makes itself; the last two it
+cannot detect, which is why they are your job.
+
+| Situation | Why |
+| --- | --- |
+| runtime dependencies changed | the container's `node_modules` was installed `--omit=dev` from the old manifest, so the new code imports something that is not there |
+| a release holds the deployment lock | an apply is in progress |
+| nothing is running for that project | there is no container to copy into |
+| **the change needs a migration** | sync never migrates, and a migration belongs with the release whose code needs it |
+| **the change is going to real users** | nothing is pushed, so nothing is reproducible from it |
+
+## Procedure
+
+1. Read the profile's `driver`. Stop unless it is `docker-compose`.
+2. Tell the user what will restart and that connections drop. Get agreement if anyone
+   is using the deployment.
+3. Run with `--build` unless the project is already built. `--build` compiles in the
+   order the images do — every `packages/*` before the apps — because a root build
+   script runs workspaces in manifest order and an app listed first would compile
+   against a workspace package's previous output.
+4. Report what was copied, which containers restarted, and that the deployment is now
+   in sync drift.
+5. Verify against the running deployment, not against the build: request a path the
+   change affects. If part of the build output is excluded (below), check one of
+   those paths too — that is the failure this exclusion exists to prevent, and it
+   does not make the page look broken.
+
+## Restoring the image
+
+```bash
+npx @podosoft/podokit deploy sync --profile <name> --revert
+```
+
+This recreates the containers from the Compose project **already on the target**,
+which is the description of what was actually applied — not a fresh render, which
+would reproduce the profile as it is now.
+
+A release does the same thing as a side effect, so `--revert` is for abandoning a
+sync, not a required cleanup step.
+
+## Excluding part of the build output
+
+Some of a build output can come from a toolchain the developer's machine does not
+have. Overwriting that part replaces real artifacts with an index of artifacts that
+are no longer there, and the application keeps serving pages while the missing files
+404 — so nothing looks broken. Those paths belong in the profile:
+
+```json
+{ "sync": { "exclude": ["apps/web/build/static-assets/generated"] } }
+```
+
+If you find yourself about to sync over something this machine cannot rebuild, add it
+here rather than remembering not to. `--clean` refuses while an exclude sits beneath
+a synced path, for the same reason.
+
+## Boundary
+
+Never use this to ship. Never run migrations alongside it. Never create or rotate
+credentials, and never print a secret value.

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

@@ -1,6 +1,6 @@
 ---
 name: podokit-deploy
-description: Plan, inspect, apply, verify, and roll back PodoKit Kubernetes releases with an explicit profile and confirmation hash. Use for Kubernetes deployment and rollback work in a generated PodoKit project.
+description: Plan, inspect, apply, verify, and roll back PodoKit releases with an explicit profile and confirmation hash, on Kubernetes or Docker Compose. Use for release, rollout, and rollback work in a generated PodoKit project.
 ---
 
 # PodoKit deployment

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

@@ -0,0 +1,8 @@
+---
+name: podokit-deploy-fast
+description: Push locally built artifacts into a running Docker Compose deployment and restart it, without building or publishing an image. Use when iterating on code against a deployed environment and a full release round trip is too slow. Not for releases, migrations, dependency changes, or anything going to real users.
+---
+
+# PodoKit fast deployment sync
+
+Read and follow the canonical skill at `../../../.agents/skills/podokit-deploy-fast/SKILL.md`.

package/dist/templates/fullstack-nest-svelte/dot-dockerignore

@@ -6,3 +6,10 @@ dist
 **/.svelte-kit
 .git
 *.log
+
+# Real environment files never enter a build context. The build stages copy the
+# whole repository, so an .env left here is baked into an image layer even when the
+# runtime stage does not copy it -- and getting-started tells you to create one.
+.env
+.env.*
+!.env.example

package/dist/templates/fullstack-nest-svelte/dot-env.example

@@ -12,6 +12,13 @@ POSTGRES_DB=podokit
 
 # Web -> API boundary (server-side only; not exposed to the browser)
 BACKEND_INTERNAL_URL=http://localhost:5002
+
+# Exact paths the web server may proxy as WebSocket upgrades to the API, comma
+# separated. Empty means none: a SvelteKit route cannot answer an upgrade, so a
+# WebSocket gateway on the API is unreachable until it is named here. Each path is
+# matched whole and must be authorised by the API at handshake time -- a relay that
+# forwards anything is an open tunnel to every private route.
+WS_PROXY_PATHS=
 CORS_ORIGIN=http://localhost:5001
 # adapter-node request limit; leave room for a 2 MiB multipart upload
 BODY_SIZE_LIMIT=3M

package/dist/templates/fullstack-nest-svelte/dot-github/workflows/release.yml

@@ -0,0 +1,142 @@
+# Build and publish the release images for a tag.
+#
+# `podo deploy` consumes images; it does not build them. This is the other half:
+# tagging a commit produces the two images that `podo deploy apply` then rolls out.
+# It stops at the push, because rolling out requires confirming a plan hash and that
+# approval belongs to a person.
+#
+# ── Which runner, and what it costs ──────────────────────────────────────────────
+#
+# 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 the most expensive job most
+# projects run. A self-hosted runner consumes no Actions minutes at all, whatever
+# the repository's visibility.
+#
+# So the runner is a variable rather than a constant:
+#
+#   PODOKIT_RUNNER   repository or organization variable, a JSON array of labels.
+#                    Unset -> ["ubuntu-latest"], which is right for a public
+#                    repository and costs money in a private one.
+#                    Self-hosted example: ["self-hosted","Linux","X64"]
+#
+# Set it before the first tag if this repository is private. Nothing here warns you
+# when you have not: the workflow succeeds either way, and the difference shows up
+# on a bill.
+#
+# ── The other two variables ──────────────────────────────────────────────────────
+#
+#   PODOKIT_DEPLOY_PROFILE   which .podokit/deploy/<name>.json names the image
+#                            repositories. Unset -> production.
+#   PODOKIT_IMAGE_PLATFORM   the architecture the deployment target runs.
+#                            Unset -> linux/amd64. Building for the wrong one
+#                            produces "exec format error" at rollout, after the
+#                            migration has already run.
+#
+# ── Secrets ──────────────────────────────────────────────────────────────────────
+#
+#   REGISTRY_USERNAME / REGISTRY_PASSWORD   credentials for the registry named by
+#   the profile. A robot or deploy account is enough, but note that some registries
+#   refuse to let a robot CREATE a repository -- push the first tag of a new
+#   repository with an account that can, or create it in the registry first.
+
+name: release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  images:
+    # One job builds both images rather than a matrix of two. A self-hosted pool is
+    # usually small, and fanning out here takes runners away from every other
+    # repository that shares it for no wall-clock gain on a multi-core machine.
+    runs-on: ${{ fromJSON(vars.PODOKIT_RUNNER || '["ubuntu-latest"]') }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci --no-audit --no-fund
+
+      # Verify before publishing. An image built from a commit that never passed is
+      # indistinguishable from one that did, once it is in the registry.
+      - run: npm run lint
+      - run: npm test
+
+      - name: Read the release target from the deployment profile
+        id: profile
+        run: |
+          node --input-type=module -e '
+            import { readFileSync } from "node:fs";
+            const name = process.env.PROFILE || "production";
+            const path = `.podokit/deploy/${name}.json`;
+            let profile;
+            try {
+              profile = JSON.parse(readFileSync(path, "utf8"));
+            } catch {
+              throw new Error(`No deployment profile at ${path}. Run podo deploy init first.`);
+            }
+            const { apiRepository, webRepository } = profile.release ?? {};
+            if (!apiRepository || !webRepository) {
+              throw new Error(`${path} does not declare release.apiRepository and release.webRepository.`);
+            }
+            // Everything before the first slash is a registry host only when it
+            // looks like one; otherwise the reference is a Docker Hub short name.
+            const first = apiRepository.split("/")[0];
+            const registry = /[.:]/.test(first) ? first : "";
+            const out = [
+              `api=${apiRepository}`,
+              `web=${webRepository}`,
+              `registry=${registry}`,
+              `tag=${process.env.GITHUB_REF_NAME}`,
+            ].join("\n");
+            process.stdout.write(out + "\n");
+          ' >> "$GITHUB_OUTPUT"
+        env:
+          PROFILE: ${{ vars.PODOKIT_DEPLOY_PROFILE }}
+
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ${{ steps.profile.outputs.registry }}
+          username: ${{ secrets.REGISTRY_USERNAME }}
+          password: ${{ secrets.REGISTRY_PASSWORD }}
+
+      - name: Build and push the API image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: apps/api/Dockerfile
+          platforms: ${{ vars.PODOKIT_IMAGE_PLATFORM || 'linux/amd64' }}
+          push: true
+          tags: ${{ steps.profile.outputs.api }}:${{ steps.profile.outputs.tag }}
+          cache-from: type=gha,scope=api
+          cache-to: type=gha,scope=api,mode=max
+
+      - name: Build and push the web image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: apps/web/Dockerfile
+          platforms: ${{ vars.PODOKIT_IMAGE_PLATFORM || 'linux/amd64' }}
+          push: true
+          tags: ${{ steps.profile.outputs.web }}:${{ steps.profile.outputs.tag }}
+          cache-from: type=gha,scope=web
+          cache-to: type=gha,scope=web,mode=max
+
+      - name: Report what to deploy
+        run: |
+          echo "Pushed ${{ steps.profile.outputs.api }}:${{ steps.profile.outputs.tag }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "Pushed ${{ steps.profile.outputs.web }}:${{ steps.profile.outputs.tag }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo 'Roll out with `podo deploy plan --profile <name> --release ${{ steps.profile.outputs.tag }}`, then apply the printed hash.' >> "$GITHUB_STEP_SUMMARY"

package/dist/templates/fullstack-nest-svelte/infra/k3s/README.md

@@ -0,0 +1,18 @@
+# Example k3s manifests
+
+These are **illustrative**. `podo deploy` does not read or apply them.
+
+For a real deployment, initialize a profile and let PodoKit render the manifests it
+will actually apply — with image digests, probes, disruption budgets, a migration
+Job, and a confirmation hash:
+
+```bash
+podo deploy init --profile production --context production --host app.example.com
+podo deploy render --profile production --release v1.2.3
+```
+
+Keep these files if you want a starting point for hand-managed manifests, or delete
+the directory if you deploy with `podo deploy`. If you do apply them by hand, replace
+every `example.com` and `ghcr.io/example/...` placeholder first, and note that the
+image tags below are placeholders too: the deployment tooling rejects `latest`,
+branch tags, and empty tags, and so should you.

package/dist/templates/fullstack-nest-svelte/infra/k3s/api-deployment.yaml

@@ -1,3 +1,4 @@
+# Example only. See README.md in this directory; `podo deploy` renders its own.
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -13,7 +14,8 @@ spec:
     spec:
       containers:
         - name: api
-          image: ghcr.io/example/podokit-api:latest
+          # Placeholder. Use one immutable, stable SemVer tag for api and web.
+          image: ghcr.io/example/podokit-api:v0.0.0
           ports:
             - containerPort: 3000
           envFrom:
@@ -22,3 +24,6 @@ spec:
           readinessProbe:
             httpGet: { path: /health/ready, port: 3000 }
             initialDelaySeconds: 5
+          livenessProbe:
+            httpGet: { path: /health, port: 3000 }
+            initialDelaySeconds: 15

package/dist/templates/fullstack-nest-svelte/infra/k3s/ingress.yaml

@@ -1,3 +1,4 @@
+# Example only. See README.md in this directory; `podo deploy` renders its own.
 apiVersion: traefik.io/v1alpha1
 kind: Middleware
 metadata:
@@ -14,6 +15,13 @@ metadata:
   annotations:
     traefik.ingress.kubernetes.io/router.middlewares: podokit-compression@kubernetescrd
 spec:
+  # Name the controller explicitly rather than relying on a default IngressClass.
+  ingressClassName: traefik
+  # app-config sets an https:// origin, so the route has to terminate TLS. Create the
+  # Secret out of band (cert-manager, or an existing certificate) and name it here.
+  tls:
+    - hosts: [example.com]
+      secretName: app-tls
   rules:
     - host: example.com
       http:

package/dist/templates/fullstack-nest-svelte/infra/k3s/web-deployment.yaml

@@ -1,3 +1,4 @@
+# Example only. See README.md in this directory; `podo deploy` renders its own.
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -13,8 +14,17 @@ spec:
     spec:
       containers:
         - name: web
-          image: ghcr.io/example/podokit-web:latest
+          # Placeholder. Use one immutable, stable SemVer tag for api and web.
+          image: ghcr.io/example/podokit-web:v0.0.0
           ports:
             - containerPort: 3000
           envFrom:
             - configMapRef: { name: app-config }
+          # Without these a rolling update sends traffic to a process that has not
+          # bound its port yet.
+          readinessProbe:
+            httpGet: { path: /, port: 3000 }
+            initialDelaySeconds: 5
+          livenessProbe:
+            httpGet: { path: /, port: 3000 }
+            initialDelaySeconds: 15

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/components/account-page.svelte

@@ -9,6 +9,7 @@
   import * as Table from "$lib/components/ui/table";
   import * as Dialog from "$lib/components/ui/dialog";
   import DataTable, { type DataTableColumn, type SortState, DEFAULT_PAGE_SIZE } from "$lib/components/data-table.svelte";
+  import { deviceLabel } from "$lib/device-label";
   import { toast } from "svelte-sonner";
   import { api } from "$lib/api";
   import { getI18n, fmt, formatDateTime } from "$lib/i18n";
@@ -382,7 +383,7 @@
   let sessionsSort = $state<SortState | null>(null);
   let busy = $state(false);
   const sessionsColumns: DataTableColumn<Session>[] = [
-    { key: "userAgent", label: i18n.t.sessions.device, sortable: true, value: (s) => s.userAgent ?? "" },
+    { key: "userAgent", label: i18n.t.sessions.device, sortable: true, value: (s) => deviceLabel(s.userAgent) ?? s.userAgent ?? "" },
     { key: "ipAddress", label: i18n.t.sessions.ip, sortable: true, value: (s) => s.ipAddress ?? "" },
     { key: "createdAt", label: i18n.t.sessions.since, sortable: true, value: (s) => new Date(s.createdAt).getTime() },
     { key: "status", label: i18n.t.sessions.status },
@@ -793,7 +794,7 @@
             >
               {#snippet row(s)}
                 {@const isCurrent = s.id === data.currentSessionId}
-                <Table.Cell class="max-w-xs truncate">{s.userAgent ?? i18n.t.sessions.unknown}</Table.Cell>
+                <Table.Cell class="max-w-xs truncate" title={s.userAgent ?? ""}>{deviceLabel(s.userAgent) ?? s.userAgent ?? i18n.t.sessions.unknown}</Table.Cell>
                 <Table.Cell class="text-muted-foreground">{s.ipAddress ?? "—"}</Table.Cell>
                 <Table.Cell class="text-muted-foreground">{formatDateTime(s.createdAt)}</Table.Cell>
                 <Table.Cell>{#if isCurrent}<Badge>{i18n.t.sessions.current}</Badge>{/if}</Table.Cell>

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/device-label.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import { deviceLabel } from "./device-label";
+
+describe("deviceLabel", () => {
+  it("names the browser and the machine", () => {
+    expect(
+      deviceLabel(
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36",
+      ),
+    ).toBe("Chrome · macOS");
+    expect(
+      deviceLabel(
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36",
+      ),
+    ).toBe("Chrome · Windows");
+  });
+
+  // Each of these contains an earlier engine's token, so a naive check in the wrong
+  // order reports every one of them as Chrome or Safari.
+  it("does not mistake a derivative for the engine it embeds", () => {
+    expect(deviceLabel("Mozilla/5.0 (Windows NT 10.0) Chrome/141.0.0.0 Safari/537.36 Edg/141.0.0.0")).toBe(
+      "Edge · Windows",
+    );
+    expect(deviceLabel("Mozilla/5.0 (Windows NT 10.0) Chrome/141.0.0.0 Safari/537.36 OPR/121.0.0.0")).toBe(
+      "Opera · Windows",
+    );
+    expect(
+      deviceLabel("Mozilla/5.0 (Linux; Android 15) AppleWebKit/537.36 Chrome/141.0.0.0 SamsungBrowser/28.0 Safari/537.36"),
+    ).toBe("Samsung Internet · Android");
+    expect(
+      deviceLabel("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 Version/18.0 Safari/605.1.15"),
+    ).toBe("Safari · macOS");
+  });
+
+  it("names an iPhone and an iPad rather than the engine's host platform", () => {
+    expect(
+      deviceLabel("Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) AppleWebKit/605.1.15 Version/18.0 Mobile/15E148 Safari/604.1"),
+    ).toBe("Safari · iPhone");
+    // iPadOS reports Macintosh in the same string, so order decides this one.
+    expect(
+      deviceLabel("Mozilla/5.0 (iPad; CPU OS 18_0 like Mac OS X) AppleWebKit/605.1.15 Version/18.0 Mobile/15E148 Safari/604.1"),
+    ).toBe("Safari · iPad");
+    expect(deviceLabel("Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) CriOS/141.0.0.0 Mobile/15E148 Safari/604.1")).toBe(
+      "Chrome · iPhone",
+    );
+  });
+
+  it("gives up on something that is not a browser, so the caller can show it raw", () => {
+    // The exact value is the whole point for these: "node" is the symptom of a
+    // proxy that forgot to forward the header, and a CLI's name identifies it.
+    expect(deviceLabel("node")).toBeNull();
+    expect(deviceLabel("curl/8.7.1")).toBeNull();
+    expect(deviceLabel("")).toBeNull();
+    expect(deviceLabel(null)).toBeNull();
+    expect(deviceLabel(undefined)).toBeNull();
+  });
+
+  it("reports whichever half it can read", () => {
+    expect(deviceLabel("Mozilla/5.0 (Windows NT 10.0; Win64; x64)")).toBe("Windows");
+    expect(deviceLabel("Firefox/142.0")).toBe("Firefox");
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/device-label.ts

@@ -0,0 +1,50 @@
+/**
+ * A readable device name for a session's user agent.
+ *
+ * The sessions tables label this column "device", and a raw user agent does not
+ * answer that question — truncated to fit a cell, every modern browser starts with
+ * the same "Mozilla/5.0 (…" and the part that differs is off the end. This reduces
+ * it to the two things someone scanning their own sessions is looking for: which
+ * browser, on which machine.
+ *
+ * Returns null when the string is not a browser at all — a CLI, a script, or the
+ * proxy's own default. The caller shows the raw value then, because for those the
+ * exact string is the only useful information.
+ */
+
+/** Order matters: every one of these also contains an earlier engine's token. */
+const BROWSERS: Array<[RegExp, string]> = [
+  [/\bEdg(?:e|A|iOS)?\//, "Edge"],
+  [/\bOPR\/|\bOpera\//, "Opera"],
+  [/\bSamsungBrowser\//, "Samsung Internet"],
+  [/\bFirefox\/|\bFxiOS\//, "Firefox"],
+  [/\bCriOS\//, "Chrome"],
+  [/\bChrome\/|\bChromium\//, "Chrome"],
+  [/\bSafari\//, "Safari"],
+];
+
+/** iPadOS reports as Macintosh, so the iPad check has to come before macOS. */
+const PLATFORMS: Array<[RegExp, string]> = [
+  [/\biPhone\b/, "iPhone"],
+  [/\biPad\b/, "iPad"],
+  [/\bAndroid\b/, "Android"],
+  [/\bCrOS\b/, "ChromeOS"],
+  [/\bWindows NT\b/, "Windows"],
+  [/\bMacintosh\b|\bMac OS X\b/, "macOS"],
+  [/\bLinux\b/, "Linux"],
+];
+
+function match(candidates: Array<[RegExp, string]>, value: string): string | null {
+  for (const [pattern, label] of candidates) {
+    if (pattern.test(value)) return label;
+  }
+  return null;
+}
+
+export function deviceLabel(userAgent: string | null | undefined): string | null {
+  if (!userAgent) return null;
+  const browser = match(BROWSERS, userAgent);
+  const platform = match(PLATFORMS, userAgent);
+  if (browser && platform) return `${browser} · ${platform}`;
+  return browser ?? platform;
+}

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(admin)/admin/sessions/+page.svelte

@@ -9,6 +9,7 @@
   import { toast } from "svelte-sonner";
   import { api } from "$lib/api";
   import { getI18n, fmt, formatDateTime } from "$lib/i18n";
+  import { deviceLabel } from "$lib/device-label";
 
   const i18n = getI18n();
 
@@ -43,7 +44,7 @@
 
   const columns = $derived<DataTableColumn<Row>[]>([
     { key: "user", label: i18n.t.adminSessions.user, sortable: true, value: (r) => r.userName },
-    { key: "device", label: i18n.t.adminSessions.device, sortable: true, value: (r) => r.userAgent },
+    { key: "device", label: i18n.t.adminSessions.device, sortable: true, value: (r) => deviceLabel(r.userAgent) ?? r.userAgent ?? "" },
     { key: "ip", label: i18n.t.adminSessions.ip, sortable: true, value: (r) => r.ipAddress },
     { key: "createdAt", label: i18n.t.adminSessions.since, sortable: true },
     { key: "expiresAt", label: i18n.t.adminSessions.expires, sortable: true, value: (r) => (r.expiresAt ? new Date(r.expiresAt).getTime() : 0) },
@@ -134,7 +135,7 @@
         </div>
         <div class="text-muted-foreground text-xs">{r.userEmail}</div>
       </Table.Cell>
-      <Table.Cell class="max-w-xs truncate">{r.userAgent ?? i18n.t.adminSessions.unknown}</Table.Cell>
+      <Table.Cell class="max-w-xs truncate" title={r.userAgent ?? ""}>{deviceLabel(r.userAgent) ?? r.userAgent ?? i18n.t.adminSessions.unknown}</Table.Cell>
       <Table.Cell class="text-muted-foreground">{r.ipAddress ?? "—"}</Table.Cell>
       <Table.Cell class="text-muted-foreground">{formatDateTime(r.createdAt)}</Table.Cell>
       <Table.Cell class="text-muted-foreground">{r.expiresAt ? formatDateTime(r.expiresAt) : "—"}</Table.Cell>

package/dist/templates/modules/admin-dashboard/files/apps/web/src/routes/(admin)/admin/users/+page.svelte

@@ -17,6 +17,7 @@
   import { api } from "$lib/api";
   import { getI18n, fmt, formatDateTime } from "$lib/i18n";
   import { cn } from "$lib/utils";
+  import { deviceLabel } from "$lib/device-label";
   import type { PageData } from "./$types";
 
   let { data }: { data: PageData } = $props();
@@ -194,7 +195,7 @@
   let mSessionsPage = $state(1);
   let mSessionsSort = $state<SortState | null>(null);
   const mSessionsColumns: DataTableColumn<Session>[] = [
-    { key: "userAgent", label: i18n.t.adminSessions.device, sortable: true },
+    { key: "userAgent", label: i18n.t.adminSessions.device, sortable: true, value: (s) => deviceLabel(s.userAgent) ?? s.userAgent ?? "" },
     { key: "ipAddress", label: i18n.t.adminSessions.ip, sortable: true },
     { key: "createdAt", label: i18n.t.adminSessions.since, sortable: true, value: (s) => new Date(s.createdAt).getTime() },
     { key: "actions", label: "", class: "w-10" },
@@ -557,7 +558,7 @@
               empty={i18n.t.adminSessions.empty}
             >
               {#snippet row(s)}
-                <Table.Cell class="max-w-40 truncate">{s.userAgent ?? i18n.t.adminSessions.unknown}</Table.Cell>
+                <Table.Cell class="max-w-40 truncate" title={s.userAgent ?? ""}>{deviceLabel(s.userAgent) ?? s.userAgent ?? i18n.t.adminSessions.unknown}</Table.Cell>
                 <Table.Cell class="text-muted-foreground">{s.ipAddress ?? "—"}</Table.Cell>
                 <Table.Cell class="text-muted-foreground">{formatDateTime(s.createdAt)}</Table.Cell>
                 <Table.Cell><Button variant="ghost" size="sm" disabled={busy} onclick={() => revokeSession(s.token)}>{i18n.t.users.revokeSession}</Button></Table.Cell>

package/dist/templates/modules/bullmq/files/infra/k3s/worker-deployment.yaml

@@ -1,3 +1,4 @@
+# Example only. See infra/k3s/README.md; `podo deploy` renders its own.
 # BullMQ worker — runs the same API image with the worker entrypoint.
 # It has no HTTP server, so there is no Service or Ingress.
 apiVersion: apps/v1
@@ -15,7 +16,7 @@ spec:
     spec:
       containers:
         - name: worker
-          image: ghcr.io/example/podokit-api:latest
+          image: ghcr.io/example/podokit-api:v0.0.0
           command: ["node", "dist/main-worker"]
           envFrom:
             - configMapRef: { name: app-config }

package/dist/templates/todo/AGENTS.md

@@ -70,7 +70,8 @@ Useful commands:
 - `podo remove <module>` — un-apply a module (inverse of add; refuses if another module needs it, keeps files you edited).
 - `podo status` / `podo diff` — see your local edits vs. what PodoKit generated.
 - `podo update` — pull in template/module improvements (3-way merges your edits; never touches owned files).
-- `podo deploy` — plan, apply, verify, or roll back an immutable Kubernetes release. Use `.agents/skills/podokit-deploy`.
+- `podo deploy` — plan, apply, verify, or roll back an immutable release on Kubernetes or one Docker host. Tag `vX.Y.Z` to build and push the images (`.github/workflows/release.yml`; check its runner — GitHub-hosted minutes are free for public repositories only). Use `.agents/skills/podokit-deploy`.
+- `podo deploy sync` — copy local build output into a running Compose deployment and restart it, for iterating without a release. Not a release: no image is published and the next `apply` discards it. Use `.agents/skills/podokit-deploy-fast`.
 
 ## Commit conventions
 

package/dist/templates/todo/Dockerfile.dev

@@ -1,6 +1,24 @@
 # Development image for the PodoKit monorepo (web + api).
 # Dependencies and source are baked in; `docker compose watch` syncs your
 # edits into the running container so the native file watchers fire.
+
+# Every workspace manifest, collected rather than listed.
+#
+# Listing them by hand only works for the workspaces this template starts with. A
+# project that adds `packages/*` then has workspace manifests that never reach the
+# image, so npm does not know those names are local and goes looking for them on the
+# public registry — `npm error 404 '@scope/thing' is not in this registry`, from an
+# install that succeeds on the developer's own machine. The production images
+# collect manifests for exactly this reason; this one was the exception until a
+# generated project with shared packages could not start its dev stack at all.
+FROM node:22-bookworm-slim AS manifests
+WORKDIR /src
+COPY . .
+RUN mkdir -p /app \
+    && cp package.json /app/ \
+    && find . -name package.json -not -path "*/node_modules/*" \
+         -exec sh -c 'mkdir -p "/app/$(dirname "$1")" && cp "$1" "/app/$1"' _ {} \;
+
 FROM node:22-bookworm-slim
 
 # git for the toolchain (editors, AI agents); build tools for native modules.
@@ -14,9 +32,7 @@ WORKDIR /app
 # NB: the host package-lock.json is intentionally NOT copied — a lockfile
 # generated on macOS/Windows prunes platform-specific optional deps and can drop
 # packages (e.g. @swc/cli) on linux. Resolving fresh in-container avoids that.
-COPY package.json ./
-COPY apps/api/package.json ./apps/api/package.json
-COPY apps/web/package.json ./apps/web/package.json
+COPY --from=manifests /app ./
 ARG PODOKIT_NPM_REGISTRY=""
 RUN if [ -n "$PODOKIT_NPM_REGISTRY" ]; then npm config set registry "$PODOKIT_NPM_REGISTRY"; fi \
   && npm install
@@ -24,4 +40,19 @@ RUN if [ -n "$PODOKIT_NPM_REGISTRY" ]; then npm config set registry "$PODOKIT_NP
 # Baked source (kept in sync during development by `docker compose watch`).
 COPY . .
 
+# Workspace packages compile before the apps that import them. Apps import them by
+# their published entry point (`dist/index.js`), so without this the API starts and
+# dies on MODULE_NOT_FOUND for a package whose symlink is right there — the link
+# resolves, the built file behind it does not exist. `--if-present` keeps a project
+# with no packages, or one whose packages need no build, working unchanged.
+#
+# `docker compose watch` syncs app source only, so a change under packages/* needs
+# this image rebuilt rather than a container restart.
+RUN if [ -d packages ]; then \
+      for manifest in packages/*/package.json; do \
+        [ -e "$manifest" ] || continue; \
+        npm run build --if-present --workspace "$(dirname "$manifest")"; \
+      done; \
+    fi
+
 EXPOSE 5001 5002