@podosoft/podokit 0.14.0 → 0.16.0

package/dist/templates/fullstack-nest-svelte/apps/api/src/health/health.controller.ts

@@ -1,10 +1,20 @@
 import { Controller, Get, ServiceUnavailableException } from "@nestjs/common";
 import { InjectDataSource } from "@nestjs/typeorm";
 import { DataSource } from "typeorm";
+import { ReadinessService, type ReadinessStatus } from "./readiness.service";
+
+interface ReadinessResponse {
+  status: "ready";
+  db: "up";
+  checks: Record<string, ReadinessStatus>;
+}
 
 @Controller("health")
 export class HealthController {
-  constructor(@InjectDataSource() private readonly dataSource: DataSource) {}
+  constructor(
+    @InjectDataSource() private readonly dataSource: DataSource,
+    private readonly readinessService: ReadinessService,
+  ) {}
 
   @Get()
   liveness(): { status: string; uptime: number; timestamp: string } {
@@ -12,12 +22,17 @@ export class HealthController {
   }
 
   @Get("ready")
-  async readiness(): Promise<{ status: string; db: string }> {
+  async readiness(): Promise<ReadinessResponse> {
+    let db: ReadinessStatus = "up";
     try {
       await this.dataSource.query("SELECT 1");
-      return { status: "ready", db: "up" };
     } catch {
-      throw new ServiceUnavailableException({ status: "degraded", db: "down" });
+      db = "down";
+    }
+    const checks = await this.readinessService.run();
+    if (db === "down" || Object.values(checks).includes("down")) {
+      throw new ServiceUnavailableException({ status: "degraded", db, checks });
     }
+    return { status: "ready", db: "up", checks };
   }
 }

package/dist/templates/fullstack-nest-svelte/apps/api/src/health/health.module.ts

@@ -1,7 +1,11 @@
-import { Module } from "@nestjs/common";
+import { Global, Module } from "@nestjs/common";
 import { HealthController } from "./health.controller";
+import { ReadinessService } from "./readiness.service";
 
+@Global()
 @Module({
   controllers: [HealthController],
+  providers: [ReadinessService],
+  exports: [ReadinessService],
 })
 export class HealthModule {}

package/dist/templates/fullstack-nest-svelte/apps/api/src/health/readiness.service.spec.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "@jest/globals";
+import { ReadinessService } from "./readiness.service";
+
+describe("ReadinessService", () => {
+  it("runs registered checks and removes them with the returned callback", async () => {
+    const service = new ReadinessService();
+    const unregister = service.register("cache", () => Promise.resolve());
+    service.register("events", () => Promise.reject(new Error("unavailable")));
+
+    await expect(service.run()).resolves.toEqual({ cache: "up", events: "down" });
+    unregister();
+    await expect(service.run()).resolves.toEqual({ events: "down" });
+  });
+
+  it("rejects duplicate names", () => {
+    const service = new ReadinessService();
+    service.register("cache", () => Promise.resolve());
+    expect(() => service.register("cache", () => Promise.resolve())).toThrow(
+      'Readiness check "cache" is already registered',
+    );
+  });
+});

package/dist/templates/fullstack-nest-svelte/apps/api/src/health/readiness.service.ts

@@ -0,0 +1,33 @@
+import { Injectable } from "@nestjs/common";
+
+export type ReadinessStatus = "up" | "down";
+export type ReadinessCheck = () => Promise<void>;
+
+@Injectable()
+export class ReadinessService {
+  private readonly checks = new Map<string, ReadinessCheck>();
+
+  register(name: string, check: ReadinessCheck): () => void {
+    if (this.checks.has(name)) {
+      throw new Error(`Readiness check "${name}" is already registered`);
+    }
+    this.checks.set(name, check);
+    return () => {
+      this.checks.delete(name);
+    };
+  }
+
+  async run(): Promise<Record<string, ReadinessStatus>> {
+    const results = await Promise.all(
+      [...this.checks].map(async ([name, check]): Promise<[string, ReadinessStatus]> => {
+        try {
+          await check();
+          return [name, "up"];
+        } catch {
+          return [name, "down"];
+        }
+      }),
+    );
+    return Object.fromEntries(results);
+  }
+}

package/dist/templates/fullstack-nest-svelte/apps/web/Dockerfile

@@ -19,11 +19,11 @@ ENV NODE_ENV=production
 # Keep the adapter-node proxy above the 2 MiB application upload policy so the
 # API can return stable validation codes after accounting for multipart framing.
 ENV BODY_SIZE_LIMIT=3M
-RUN addgroup -S app && adduser -S app -G app
+RUN addgroup -S -g 101 app && adduser -S -D -H -u 100 -G app app
 COPY --from=build /app/node_modules ./node_modules
 COPY --from=deps /app/apps/web ./apps/web
 COPY --from=build /app/apps/web/build ./apps/web/build
 WORKDIR /app/apps/web
-USER app
+USER 100:101
 EXPOSE 3000
 CMD ["node", "build"]

package/dist/templates/fullstack-nest-svelte/apps/web/src/app.html

@@ -2,6 +2,8 @@
 <html lang="en" class="h-full">
   <head>
     <meta charset="utf-8" />
+    <!-- Add viewport-fit=cover only when the application-owned layout also
+         handles env(safe-area-inset-*) padding for edge-to-edge content. -->
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>{{projectName}}</title>
     <link rel="icon" href="/favicon.svg" type="image/svg+xml" />

package/dist/templates/fullstack-nest-svelte/compose.dev.yaml

@@ -1,16 +1,14 @@
 # Containerized development environment.
 #
-#   podo dev watch                                                # core stack
-#   podo dev watch --profile cache --profile storage \
-#     --profile queue                                             # with modules
+#   podo dev watch   # installed modules activate their required profiles
 #
 # A user-level PodoKit gateway owns loopback :80 and routes each *.localhost host
 # to this stack. The legacy per-project Traefik service is opt-in only.
 # api/postgres/redis/minio have NO published ports — they talk by service name
 # on the internal network, so this stack never collides with other projects.
 #
-# Core services (traefik, web, api, postgres) always run. Module-specific
-# services are behind profiles — enable the ones your app uses:
+# Core services (traefik, web, api, postgres) always run. PodoKit activates
+# module-specific profiles from .podokit/manifest.json:
 #   --profile cache    redis    (redis / rate-limit / bullmq modules)
 #   --profile storage  minio    (object-storage-s3 / file-upload modules)
 #   --profile queue    worker   (bullmq / job-progress modules)

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

@@ -0,0 +1,20 @@
+---
+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.
+---
+
+# Deploy a PodoKit application
+
+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.
+
+For rollback, read [references/rollback.md](references/rollback.md), preview the target revision without `--confirm`, show the new plan hash, and obtain explicit approval.
+
+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.

package/dist/templates/fullstack-nest-svelte/dot-agents/skills/podokit-deploy/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "PodoKit Deploy"
+  short_description: "Plan and verify safe Kubernetes releases"
+  default_prompt: "Use $podokit-deploy to inspect and plan this PodoKit Kubernetes release safely."

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

@@ -0,0 +1,37 @@
+# Deployment profile
+
+The profile at `.podokit/deploy/<name>.json` is application-owned and contains no Secret values.
+
+Initialize it with an explicit kubeconfig context:
+
+```bash
+npx @podosoft/podokit deploy init --profile production --context production --host app.example.com
+```
+
+Review these fields before planning:
+
+- `target`: context, cluster fingerprint, namespace, release
+- `release`: API/web repositories and stable SemVer tag pattern
+- `exposure`: Ingress or NodePort; Ingress routes every public path to web
+- `workloads`: API/web replicas and resources plus an optional worker
+- `dependencies`: PostgreSQL, Redis, and object storage mode, image, Secret name, and storage
+- `secrets`: API/optional web Secret names and required key names, plus image-pull Secret
+- `runtimeConfig`: non-sensitive environment values only
+- `verification`: HTTPS origin and checks with exact statuses and optional JSON fields
+
+The cluster namespace and referenced Secrets must already exist. PodoKit asks `kubectl` to output only Secret key names and never prints or stores their values; the Kubernetes client still materializes the Secret while evaluating that output.
+
+Required keys:
+
+| Secret | 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` |
+| image pull | A `kubernetes.io/dockerconfigjson` Secret |
+
+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.

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

@@ -0,0 +1,18 @@
+# Application rollback
+
+Inspect status and Helm history before choosing a revision:
+
+```bash
+npx @podosoft/podokit deploy status --profile production --json
+helm history <release> --namespace <namespace> --kube-context <context>
+```
+
+Preview a rollback:
+
+```bash
+npx @podosoft/podokit deploy rollback --profile production --revision <number>
+```
+
+Show the target revision, current revision, context, namespace, warning, and generated plan hash. Obtain explicit approval, then pass that exact hash with `--confirm`.
+
+Rollback changes only the application Helm release. It does not reverse database migrations, change the dependency release, delete PersistentVolumeClaims, or delete Secrets. If the old application is incompatible with the current database schema, do not roll back; prepare a forward fix instead.

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

@@ -0,0 +1,8 @@
+---
+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.
+---
+
+# PodoKit deployment
+
+Read and follow the canonical skill at `../../../.agents/skills/podokit-deploy/SKILL.md`.

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

@@ -21,3 +21,9 @@ BODY_SIZE_LIMIT=3M
 # job-progress, sse). Start it with: docker compose --profile cache up
 REDIS_HOST=localhost
 REDIS_PORT=6379
+# REDIS_URL takes precedence over the individual settings below.
+# REDIS_URL=rediss://user:password@cache.example.com:6380/0
+REDIS_DB=0
+# REDIS_USERNAME=
+# REDIS_PASSWORD=
+REDIS_TLS=false

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

@@ -20,5 +20,5 @@ spec:
             - configMapRef: { name: app-config }
             - secretRef: { name: app-secrets }
           readinessProbe:
-            httpGet: { path: /health, port: 3000 }
+            httpGet: { path: /health/ready, port: 3000 }
             initialDelaySeconds: 5

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

@@ -18,10 +18,6 @@ spec:
     - host: example.com
       http:
         paths:
-          - path: /api
-            pathType: Prefix
-            backend:
-              service: { name: api, port: { number: 3000 } }
           - path: /
             pathType: Prefix
             backend:

package/dist/templates/fullstack-nest-svelte/tests/playwright.config.ts

@@ -1,10 +1,15 @@
 import { defineConfig, devices } from "@playwright/test";
+import { loadPlaywrightProjects } from "./playwright.extensions";
 
 // The suite runs against a live stack: web on E2E_BASE_URL (proxying /api/* to
 // the API). Start it first (see docs/testing.md) — locally via the dev harness,
 // in CI via scripts/e2e-ci.mjs. Two projects: `api` (request-only, backend e2e)
 // and `ui` (chromium, pages). Files are routed by suffix (*.api/*.ui.spec.ts).
 const baseURL = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const coreProjects = [
+  { name: "api", testMatch: /.*\.api\.spec\.ts/ },
+  { name: "ui", testMatch: /.*\.ui\.spec\.ts/, use: { ...devices["Desktop Chrome"] } },
+];
 
 export default defineConfig({
   testDir: ".",
@@ -18,8 +23,5 @@ export default defineConfig({
     trace: "on-first-retry",
     screenshot: "only-on-failure",
   },
-  projects: [
-    { name: "api", testMatch: /.*\.api\.spec\.ts/ },
-    { name: "ui", testMatch: /.*\.ui\.spec\.ts/, use: { ...devices["Desktop Chrome"] } },
-  ],
+  projects: [...coreProjects, ...loadPlaywrightProjects(coreProjects)],
 });

package/dist/templates/fullstack-nest-svelte/tests/playwright.extensions.ts

@@ -0,0 +1,44 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import type { TestConfig } from "@playwright/test";
+
+type Projects = NonNullable<TestConfig["projects"]>;
+
+const requireFromTests = createRequire(__filename);
+
+function projectName(project: unknown): string | null {
+  if (typeof project !== "object" || project === null || !("name" in project)) return null;
+  return typeof project.name === "string" && project.name.length > 0 ? project.name : null;
+}
+
+/**
+ * Merge application-owned Playwright projects into PodoKit's managed config.
+ * The optional CommonJS file stays owned so applications can add devices and
+ * browsers without creating a 3-way merge hotspot in playwright.config.ts.
+ */
+export function loadPlaywrightProjects(coreProjects: Projects): Projects {
+  const extensionPath = join(__dirname, "playwright.projects.cjs");
+  if (!existsSync(extensionPath)) return [];
+
+  const loaded = requireFromTests(extensionPath) as unknown;
+  if (!Array.isArray(loaded)) {
+    throw new Error("tests/playwright.projects.cjs must export an array of Playwright projects.");
+  }
+
+  const names = new Set(
+    coreProjects.map((project) => projectName(project)).filter((name): name is string => name !== null),
+  );
+  for (const project of loaded) {
+    const name = projectName(project);
+    if (!name) {
+      throw new Error("Every project in tests/playwright.projects.cjs must have a non-empty name.");
+    }
+    if (names.has(name)) {
+      throw new Error(`Duplicate Playwright project name: ${name}`);
+    }
+    names.add(name);
+  }
+
+  return loaded as Projects;
+}

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

@@ -7,12 +7,30 @@
   import LayoutDashboardIcon from "@lucide/svelte/icons/layout-dashboard";
   import LogOutIcon from "@lucide/svelte/icons/log-out";
   import UserIcon from "@lucide/svelte/icons/user";
+  import ChevronsUpDownIcon from "@lucide/svelte/icons/chevrons-up-down";
   import { api } from "$lib/api";
   import { getI18n } from "$lib/i18n";
+  import { cn } from "$lib/utils";
   import type { SessionUser } from "../../app.d.ts";
   import UserAvatar from "./user-avatar.svelte";
 
-  let { user }: { user: SessionUser | null } = $props();
+  type MenuSide = "top" | "right" | "bottom" | "left";
+  type MenuAlign = "start" | "center" | "end";
+  type Props = {
+    user: SessionUser | null;
+    variant?: "avatar" | "identity";
+    side?: MenuSide;
+    align?: MenuAlign;
+    class?: string;
+  };
+
+  let {
+    user,
+    variant = "avatar",
+    side = "bottom",
+    align = "end",
+    class: className,
+  }: Props = $props();
   const i18n = getI18n();
   const loginHref = $derived(withAuthRedirect("/login", currentPath(page.url)));
 
@@ -27,12 +45,25 @@
   <DropdownMenu.Root>
     <DropdownMenu.Trigger
       data-testid="account-menu"
-      class="hover:bg-muted focus-visible:border-ring focus-visible:ring-ring/50 inline-flex size-8 items-center justify-center rounded-full outline-none focus-visible:ring-3"
+      class={cn(
+        "hover:bg-muted focus-visible:border-ring focus-visible:ring-ring/50 outline-none focus-visible:ring-3",
+        variant === "avatar"
+          ? "inline-flex size-8 items-center justify-center rounded-full"
+          : "flex w-full items-center gap-2 rounded-md p-2 text-left",
+        className,
+      )}
       aria-label={i18n.t.nav.account}
     >
       <UserAvatar {user} class="size-8" />
+      {#if variant === "identity"}
+        <div class="min-w-0 flex-1 text-sm leading-tight">
+          <span class="block truncate font-medium">{user.name}</span>
+          <span class="text-muted-foreground block truncate text-xs">{user.email}</span>
+        </div>
+        <ChevronsUpDownIcon class="size-4 shrink-0" />
+      {/if}
     </DropdownMenu.Trigger>
-    <DropdownMenu.Content align="end" class="w-56">
+    <DropdownMenu.Content {align} {side} class="w-56">
       <DropdownMenu.Label>
         <span class="block truncate font-medium">{user.name}</span>
         <span class="text-muted-foreground block truncate text-xs font-normal">{user.email}</span>
@@ -47,5 +78,5 @@
     </DropdownMenu.Content>
   </DropdownMenu.Root>
 {:else}
-  <Button data-testid="sign-in-link" href={loginHref} variant="ghost">{i18n.t.auth.signIn}</Button>
+  <Button data-testid="sign-in-link" href={loginHref} variant="ghost" class={className}>{i18n.t.auth.signIn}</Button>
 {/if}

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

@@ -1,14 +1,34 @@
 <script lang="ts" module>
+  import { cn } from "$lib/utils";
+
+  export type DataTableBreakpoint = "sm" | "md" | "lg" | "xl";
   export type DataTableColumn<Row> = {
     key: string;
     label: string;
     sortable?: boolean;
     class?: string;
+    hideBelow?: DataTableBreakpoint;
     // Value used for client-side sorting (defaults to row[key]). Use for nested
     // or derived fields, e.g. (s) => s.user.email.
     value?: (row: Row) => string | number | boolean | Date | null | undefined;
   };
   export type SortState = { key: string; dir: "asc" | "desc" };
+  export type DataTableRowContext = {
+    cellClass: (columnKey: string) => string | undefined;
+  };
+
+  const HIDE_BELOW_CLASS: Record<DataTableBreakpoint, string> = {
+    sm: "max-sm:hidden",
+    md: "max-md:hidden",
+    lg: "max-lg:hidden",
+    xl: "max-xl:hidden",
+  };
+
+  export function getDataTableColumnClass<Row>(
+    column: DataTableColumn<Row>,
+  ): string | undefined {
+    return cn(column.class, column.hideBelow ? HIDE_BELOW_CLASS[column.hideBelow] : undefined);
+  }
 
   // Shared page size for all admin tables — sized so a desktop viewport shows a
   // full list at a glance (rather than the old 5-row pages). Change it here to
@@ -33,9 +53,10 @@
   type Props = {
     columns: DataTableColumn<Row>[];
     rows: Row[];
-    row: Snippet<[Row]>; // renders the <Table.Cell>s for one row
+    row: Snippet<[Row, DataTableRowContext]>; // renders the <Table.Cell>s for one row
     getKey?: (row: Row, index: number) => string | number;
     empty?: string;
+    ariaLabel?: string;
     sort?: SortState | null;
     manualSort?: boolean;
     page?: number;
@@ -51,6 +72,7 @@
     row,
     getKey = (_r, i) => i,
     empty = "No data.",
+    ariaLabel,
     sort = $bindable(null),
     manualSort = false,
     page = $bindable(1),
@@ -71,6 +93,13 @@
     onChange?.({ sort, page });
   }
 
+  function cellClass(columnKey: string): string | undefined {
+    const column = columns.find((candidate) => candidate.key === columnKey);
+    return column ? getDataTableColumnClass(column) : undefined;
+  }
+
+  const rowContext: DataTableRowContext = { cellClass };
+
   function cmp(a: unknown, b: unknown): number {
     if (a == null && b == null) return 0;
     if (a == null) return -1;
@@ -95,12 +124,12 @@
 </script>
 
 <div class="rounded-md border">
-  <Table.Root>
+  <Table.Root aria-label={ariaLabel}>
     <Table.Header>
       <Table.Row>
         {#each columns as col (col.key)}
           <Table.Head
-            class={col.class}
+            class={getDataTableColumnClass(col)}
             aria-sort={sort?.key === col.key ? (sort.dir === "asc" ? "ascending" : "descending") : undefined}
           >
             {#if col.sortable}
@@ -121,7 +150,7 @@
     </Table.Header>
     <Table.Body>
       {#each view as r, i (getKey(r, i))}
-        <Table.Row>{@render row(r)}</Table.Row>
+        <Table.Row>{@render row(r, rowContext)}</Table.Row>
       {:else}
         <Table.Row>
           <Table.Cell colspan={columns.length} class="text-muted-foreground py-8 text-center">{empty}</Table.Cell>

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

@@ -4,6 +4,10 @@
   import { site, type SiteSettings } from "$lib/site.svelte";
   import { applyTheme, themeConfigFromSettings } from "$lib/site/apply-theme";
   import SessionIdleTimeout from "$lib/components/session-idle-timeout.svelte";
+  // Optional modules add global runtime components here without taking
+  // ownership of the application's root layout.
+  // podokit:begin:site-runtime-imports
+  // podokit:end:site-runtime-imports
 
   const loadedSite = $derived(
     (page.data as { site?: Partial<SiteSettings> | null }).site,
@@ -42,3 +46,5 @@
 
 <ModeWatcher />
 <SessionIdleTimeout timeoutMinutes={sessionIdleTimeoutMinutes} />
+<!-- podokit:begin:site-runtime-components -->
+<!-- podokit:end:site-runtime-components -->

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

@@ -16,6 +16,7 @@
   import { toast } from "svelte-sonner";
   import { api } from "$lib/api";
   import { getI18n, fmt, formatDateTime } from "$lib/i18n";
+  import { cn } from "$lib/utils";
   import type { PageData } from "./$types";
 
   let { data }: { data: PageData } = $props();
@@ -58,9 +59,15 @@
   const columns = $derived<DataTableColumn<Row>[]>([
     { key: "name", label: i18n.t.users.name, sortable: true },
     { key: "email", label: i18n.t.users.email, sortable: true },
-    { key: "role", label: i18n.t.users.role, sortable: true },
-    { key: "status", label: i18n.t.users.status },
-    { key: "createdAt", label: i18n.t.users.joined, sortable: true, value: (u) => (u.createdAt ? new Date(u.createdAt).getTime() : 0) },
+    { key: "role", label: i18n.t.users.role, sortable: true, hideBelow: "md" },
+    { key: "status", label: i18n.t.users.status, hideBelow: "lg" },
+    {
+      key: "createdAt",
+      label: i18n.t.users.joined,
+      sortable: true,
+      hideBelow: "lg",
+      value: (u) => (u.createdAt ? new Date(u.createdAt).getTime() : 0),
+    },
     { key: "actions", label: "", class: "w-10" },
   ]);
   const filters = $derived<ToolbarFilter[]>([
@@ -380,13 +387,14 @@
     bind:sort
     bind:page
     perPage={PAGE_SIZE}
+    ariaLabel={i18n.t.users.title}
     label={fmt(i18n.t.users.total, { count: filtered.length })}
   >
-    {#snippet row(user)}
-      <Table.Cell class="font-medium">{user.name}</Table.Cell>
-      <Table.Cell class="text-muted-foreground">{user.email}</Table.Cell>
-      <Table.Cell><Badge variant={user.role === "admin" ? "default" : "secondary"}>{user.role ?? "user"}</Badge></Table.Cell>
-      <Table.Cell>
+    {#snippet row(user, { cellClass })}
+      <Table.Cell class={cn(cellClass("name"), "font-medium")}>{user.name}</Table.Cell>
+      <Table.Cell class={cn(cellClass("email"), "text-muted-foreground")}>{user.email}</Table.Cell>
+      <Table.Cell class={cellClass("role")}><Badge variant={user.role === "admin" ? "default" : "secondary"}>{user.role ?? "user"}</Badge></Table.Cell>
+      <Table.Cell class={cellClass("status")}>
         <div class="flex flex-wrap gap-1">
           {#if user.signupApproved === false}
             <Badge variant="secondary">{i18n.t.users.pendingApproval}</Badge>
@@ -400,8 +408,8 @@
           {/if}
         </div>
       </Table.Cell>
-      <Table.Cell class="text-muted-foreground">{user.createdAt ? formatDateTime(user.createdAt) : "—"}</Table.Cell>
-      <Table.Cell>
+      <Table.Cell class={cn(cellClass("createdAt"), "text-muted-foreground")}>{user.createdAt ? formatDateTime(user.createdAt) : "—"}</Table.Cell>
+      <Table.Cell class={cellClass("actions")}>
         <DropdownMenu.Root>
           <DropdownMenu.Trigger>
             {#snippet child({ props })}

package/dist/templates/modules/admin-dashboard/files/dot-claude/skills/podokit-data-table/SKILL.md

@@ -13,19 +13,20 @@ put pagination outside the table.
 ```svelte
 <script lang="ts">
   import DataTable from "$lib/components/data-table.svelte";
+  import { cn } from "$lib/utils";
   const columns = [
     { key: "name", label: "Name", sortable: true },
     { key: "email", label: "Email", sortable: true },
-    { key: "role", label: "Role", sortable: true },     // action/status columns: no `sortable`
+    { key: "role", label: "Role", sortable: true, hideBelow: "md" },
   ];
   let { rows } = $props();   // Svelte 5 runes only
 </script>
 
-<DataTable {columns} {rows} label="{rows.length} users">
-  {#snippet row(item)}
-    <Table.Cell>{item.name}</Table.Cell>
-    <Table.Cell>{item.email}</Table.Cell>
-    <Table.Cell>{item.role}</Table.Cell>
+<DataTable {columns} {rows} ariaLabel="Users" label="{rows.length} users">
+  {#snippet row(item, { cellClass })}
+    <Table.Cell class={cellClass("name")}>{item.name}</Table.Cell>
+    <Table.Cell class={cellClass("email")}>{item.email}</Table.Cell>
+    <Table.Cell class={cn(cellClass("role"), "text-muted-foreground")}>{item.role}</Table.Cell>
   {/snippet}
 </DataTable>
 ```
@@ -34,6 +35,10 @@ put pagination outside the table.
 - **Server data** (huge lists): use `manualSort` + `manualPagination` + `total`
   + `onChange` (re-fetch with `sortBy`/`sortDirection`/`page`).
 - Nested/derived sort keys: give the column a `value` accessor.
+- Responsive columns: set `hideBelow` to `sm`, `md`, `lg`, or `xl`, then apply
+  `cellClass(columnKey)` to the matching `Table.Cell`. Never repeat the
+  responsive class by hand; the shared class keeps headers and cells aligned.
+- Give each table an `ariaLabel` and scope Playwright locators to that table.
 - No footer needed: `perPage={0}`.
 - **Search & filters**: put the shared `table-toolbar.svelte` (`TableToolbar`)
   above the DataTable. Filters + search apply together on the Search button/Enter