@podosoft/podokit 1.5.0 → 1.6.0

package/dist/templates/fullstack/compose.dev.yaml

@@ -48,6 +48,7 @@ services:
         - { action: sync, path: ./apps/web/src, target: /app/apps/web/src }
         - { action: sync, path: ./apps/web/static, target: /app/apps/web/static }
         - { action: sync+restart, path: ./apps/web/vite.config.ts, target: /app/apps/web/vite.config.ts }
+        - { action: sync+restart, path: ./apps/web/vite.extensions.ts, target: /app/apps/web/vite.extensions.ts }
         - { action: rebuild, path: ./apps/web/package.json }
 
   api:
@@ -121,7 +122,7 @@ services:
     mem_limit: ${MINIO_MEM_LIMIT:-512m}
     memswap_limit: ${MINIO_MEM_LIMIT:-512m}
     profiles: [storage]
-    image: pgsty/silo:RELEASE.2026-09-16T00-00-00Z
+    image: pgsty/silo:RELEASE.2026-09-16T00-00-00Z@sha256:635197cb9f36d01bee221d34d1c7d7960f6a95c48b0b6c01d99cd13bdae51a46
     command: server /data --console-address ":9001"
     environment:
       MINIO_ROOT_USER: podokit
@@ -134,15 +135,17 @@ services:
     mem_limit: ${MINIO_INIT_MEM_LIMIT:-128m}
     memswap_limit: ${MINIO_INIT_MEM_LIMIT:-128m}
     profiles: [storage]
-    image: pgsty/mc:RELEASE.2026-09-16T00-00-00Z
+    image: pgsty/mc:RELEASE.2026-09-16T00-00-00Z@sha256:cfc83108c3abb371f8fb84d99c1fdc88f8c237e022409b0081fb7c0a3be634dd
     depends_on:
       minio: { condition: service_started }
+    # -e stops at the first failing command, so a bucket that cannot be
+    # created fails this service instead of leaving uploads to fail later.
     entrypoint:
       - sh
-      - -c
+      - -ec
       - |
         until mc alias set loc http://minio:9000 podokit podokitsecret; do sleep 1; done
-        mc mb -p loc/podokit || true
+        mc mb --ignore-existing loc/podokit
     networks: [podokit]
 
 networks:

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

@@ -16,9 +16,9 @@ Read the profile's `driver` first and say which one you are operating.
 1. Run `{{packageExecutor}} @podosoft/podokit status`, `{{packageExecutor}} @podosoft/podokit diff`, and `{{packageExecutor}} @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. 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 `{{packageExecutor}} @podosoft/podokit deploy doctor --profile <name>`. Resolve every failure without printing secret values.
+4. Run `{{packageExecutor}} @podosoft/podokit deploy doctor --profile <name>`. Resolve every `FAIL` line and show the user every `warn` line, without printing secret values.
 5. Run `{{packageExecutor}} @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.
+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, every plan warning, and the plan hash.
 7. Do not apply until the user explicitly approves that exact plan.
 8. Apply with `{{packageExecutor}} @podosoft/podokit deploy apply --profile <name> --release <stable-semver> --confirm <plan-hash>`.
 9. Run `{{packageExecutor}} @podosoft/podokit deploy status --profile <name> --json` and `{{packageExecutor}} @podosoft/podokit deploy verify --profile <name> --json`.

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

@@ -24,9 +24,16 @@ Review these fields before planning:
   `stripPrefix` Middleware sends them to API without `/api`. It needs a
   Traefik-served IngressClass, and `/api/auth` is rejected. `podo deploy init`
   and `podo add` fill in the paths installed modules declare (file-upload:
-  `/api/files/uploads/`); keep them.
+  `/api/files/uploads/`); keep them. `edgeProxies` counts the reverse proxies in
+  front of the Ingress controller or NodePort (default 0); the web server then
+  trusts that many plus the controller in `X-Forwarded-For`. Never set
+  `XFF_DEPTH`, `ADDRESS_HEADER`, `TRUSTED_PROXY_HOPS`, or `TRUSTED_PROXY_HEADER`
+  in `runtimeConfig`; the profile refuses them.
 - `workloads`: API/web replicas and resources plus an optional worker
-- `dependencies`: PostgreSQL, Redis, and object storage mode, image, Secret name, and storage
+- `dependencies`: PostgreSQL, Redis, and object storage mode, image, Secret name, and storage.
+  PostgreSQL also takes `maxConnections` (default 100) and `appPools` for pools the
+  application opens itself; the doctor and the plan check the connection budget
+  against them, so lower `DB_POOL_MAX`/`DB_AUTH_POOL_MAX` or replicas when they warn.
 - `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
@@ -72,7 +79,9 @@ The fields that differ from the Kubernetes driver:
   it, sends exact WebSocket paths to API, sends `apiPaths` prefixes to API with
   `/api` removed, and sends every other request to web. Forwarding headers are trusted
   only from the direct proxy CIDRs in `trustedProxyCidrs`; leave it empty without an
-  external proxy. The bind address defaults to `127.0.0.1`, because the expected
+  external proxy. `edgeProxies` counts the reverse proxies in front of the published
+  port (default 1); with the gateway it must match `trustedProxyCidrs`, which the
+  doctor checks. The bind address defaults to `127.0.0.1`, because the expected
   front door is a trusted reverse proxy — binding every interface publishes the app
   before TLS exists.
 - `workloads`: replicas plus Compose `cpus` and `memory` limits

package/dist/templates/fullstack/dot-claude/skills/podokit-update/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: podokit-update
-description: Use when the user wants to update a Bun-based project to a newer PodoKit v1 version, pull in template/module improvements, check local edits, or take ownership of a managed file. Covers podo status/diff/doctor/update/eject.
+description: Use when the user wants to update a Bun-based project to a newer PodoKit v1 version, pull in template/module improvements, check local edits, or take ownership of a managed file. Covers podo status/diff/doctor/update/eject/restore.
 ---
 
 # Keep a PodoKit project up to date
@@ -11,15 +11,18 @@ its own files while keeping the user's changes.
 ```bash
 podo status          # version, modules, file tiers, and how many managed files were edited
 podo diff            # list the PodoKit-managed files you've edited (owned files ignored)
+podo diff <path>     # line diff of one file against the template (owned files too)
 podo doctor          # check framework versions vs. the supported ranges
 podo update          # dry-run: preview what a newer version would change (writes nothing)
 podo update --apply  # apply it — clean updates are written; your edits are 3-way merged
 podo eject <path>    # take ownership of a managed file so update skips it
+podo restore <path>  # rewrite a managed file from the template; re-manages an ejected file
 ```
 
 Rules to respect:
 - **owned** files (routes, your components, `AGENTS.md`, shadcn `ui/**`) are never
-  touched by `update`.
+  touched by `update`. When their template changes, the plan lists them as
+  `review`; compare with `podo diff <path>` and copy what the app needs.
 - **assembled** files are recomputed from the module set — keep edits **outside**
   the `// podokit:begin…end` fences.
 - Run `podo update` (dry-run) first and read the plan before `--apply`. Commit or

package/dist/templates/fullstack/dot-env.docker.example

@@ -18,11 +18,14 @@ TRUSTED_PROXY_HOPS=1
 # response headers.
 # BACKEND_TIMEOUT_MS=2000
 # BACKEND_PROXY_TIMEOUT_MS=30000
-CORS_ORIGIN=http://{{projectName}}.localhost,http://localhost
+# podo dev sets CORS_ORIGIN and BETTER_AUTH_URL for web and api from
+# .podokit/dev.json. These two serve compose.dev.yaml run without podo dev,
+# such as from the devcontainer.
+CORS_ORIGIN={{devCorsOrigin}}
 REDIS_HOST=redis
 REDIS_PORT=6379
 BETTER_AUTH_SECRET=
-BETTER_AUTH_URL=http://{{projectName}}.localhost
+BETTER_AUTH_URL={{devAuthUrl}}
 ADMIN_EMAILS=admin@example.com
 AUDIT_LOG_ENABLED=true
 RATE_LIMIT_TTL=60

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

@@ -3,9 +3,13 @@
 # ── Required (runtime) ───────────────────────────────────────────────
 NODE_ENV=development
 PORT=5002
+# Address the API listens on (default 0.0.0.0); 127.0.0.1 keeps it off the network.
+# HOST=0.0.0.0
 
 # Canonical database connection. Set this for PostgreSQL or SQLite; POSTGRES_* remains a fallback.
 # DATABASE_URL=postgres://podokit:podokit@localhost:5432/podokit
+# With SQLite and no DATABASE_URL, the database file, relative to apps/api.
+# SQLITE_PATH=./data/podokit.sqlite
 POSTGRES_HOST=localhost
 POSTGRES_PORT=5432
 POSTGRES_USER=podokit

package/dist/templates/fullstack/dot-podokit/dev.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "hostname": "{{projectName}}.localhost",
+  "hostname": "{{devHostname}}",
   "webSocketPaths": [],
   "apiPaths": []
 }

package/dist/templates/fullstack/infra/k3s/configmap.yaml

@@ -16,3 +16,4 @@ data:
   HOST_HEADER: "x-forwarded-host"
   ADDRESS_HEADER: "x-forwarded-for"
   XFF_DEPTH: "1"
+  # podokit:end:runtime-config

package/dist/templates/fullstack/tests/README.md

@@ -13,9 +13,48 @@ The suite runs against a live stack (web on `E2E_BASE_URL`, proxying `/api/*` to
 the API). With the recommended containerized loop, start `podo dev watch` and run:
 
 ```bash
-E2E_BASE_URL=http://{{projectName}}.localhost {{rootRun}} test:e2e
+E2E_BASE_URL=http://{{devHostname}} {{rootRun}} test:e2e
 ```
 
 The default `http://localhost:5001` is for the alternative `{{rootRun}} dev`
 host-process loop. Files ending in `*.api.spec.ts` run in the request-only `api`
 project; `*.ui.spec.ts` run in the chromium `ui` project.
+
+## Workers and exclusive tests
+
+The suite runs on one worker unless `E2E_WORKERS` says otherwise. For the whole
+suite, more workers finish sooner:
+
+```bash
+E2E_WORKERS=2 {{rootRun}} test:e2e
+```
+
+Set the count with `E2E_WORKERS`, not `--workers`: the global setup refuses more
+than one worker when `E2E_WORKERS` is unset.
+
+Every test shares one API, database, mail catcher, and SMS sink. A test that
+changes state other tests rely on takes the `@exclusive` tag:
+
+```ts
+test("maintenance mode holds visitors back", { tag: "@exclusive" }, async ({ page }) => {
+  // ...
+});
+```
+
+Tag a test when it changes a server-wide setting (a feature flag, the
+authentication configuration such as SMTP, social providers, or sign-up
+approval, the site settings, or a module's settings) or the profile of a seeded
+account. Each project has an `<name>-exclusive` twin, such as `ui-exclusive`,
+that runs only the tagged tests, one at a time. With more than one worker the
+twins wait for every other test, so an exclusive test never runs alongside
+another one. Never empty the shared mail catcher or SMS sink in a test: send to
+an address or number of the test's own instead.
+
+More than one worker suits the whole suite. When a run selects exclusive tests
+with a file name, `--grep`, or `--project`, Playwright also runs every other test
+first, because the twins depend on them, and a test that fails there marks the
+exclusive tests as not run. Use the default single worker for a few files, and
+do not combine `--no-deps` with `E2E_WORKERS` above 1.
+
+Application-owned projects in `playwright.projects.cjs` get twins too. A project
+that another project depends on is a setup project and keeps a single copy.

package/dist/templates/fullstack/tests/helpers/app-paths.ts

@@ -0,0 +1,18 @@
+import type { AppPaths } from "./paths";
+
+/**
+ * Where this application's screens differ from the generated ones, for the
+ * managed e2e specs. PodoKit creates this file once and never overwrites it.
+ * Set only what differs; `paths.ts` documents each entry and its default. For
+ * example, an app whose first screen is a signed-in workspace without a
+ * heading, and which shows no public footer:
+ *
+ * ```ts
+ * export const appPaths: Partial<AppPaths> = {
+ *   homeReady: (page) => page.getByTestId("workspace"),
+ *   indexable: [],
+ *   footer: null,
+ * };
+ * ```
+ */
+export const appPaths: Partial<AppPaths> = {};

package/dist/templates/fullstack/tests/helpers/paths.ts

@@ -0,0 +1,33 @@
+import type { Locator, Page } from "@playwright/test";
+import { appPaths } from "./app-paths";
+
+/**
+ * The application screens managed specs visit. The defaults describe the
+ * generated pages; `app-paths.ts`, which the application owns, overrides any
+ * of them, so a managed spec never needs editing for an app's own screens.
+ */
+export interface AppPaths {
+  /** The first screen a visitor opens. */
+  home: string;
+  /** Visible once the first screen has rendered. */
+  homeReady: (page: Page) => Locator;
+  /** Public pages search engines may index: they carry no `X-Robots-Tag`. */
+  indexable: string[];
+  /** A public page that renders the managed `SiteFooter`, or null when none does. */
+  footer: string | null;
+  /**
+   * A page that renders the managed `LanguageSwitch`, `ThemeToggle`, and
+   * `AccountMenu` for a signed-in user, or null when none does.
+   */
+  accountMenu: string | null;
+}
+
+const defaults: AppPaths = {
+  home: "/",
+  homeReady: (page) => page.getByRole("heading", { level: 1 }),
+  indexable: ["/"],
+  footer: "/login",
+  accountMenu: "/",
+};
+
+export const paths: AppPaths = { ...defaults, ...appPaths };

package/dist/templates/fullstack/tests/package.json

@@ -4,8 +4,8 @@
   "private": true,
   "scripts": {
     "test:e2e": "bunx playwright test",
-    "test:e2e:ui": "bunx playwright test --project=ui",
-    "test:e2e:api": "bunx playwright test --project=api",
+    "test:e2e:ui": "bunx playwright test --project=ui --project=ui-exclusive",
+    "test:e2e:api": "bunx playwright test --project=api --project=api-exclusive",
     "test:e2e:report": "bunx playwright show-report"
   },
   "devDependencies": {

package/dist/templates/fullstack/tests/playwright.config.ts

@@ -1,11 +1,14 @@
 import { defineConfig, devices } from "@playwright/test";
-import { loadPlaywrightProjects } from "./playwright.extensions";
+import { e2eWorkers, loadPlaywrightProjects, withExclusivePhase } 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).
+// E2E_WORKERS sets the worker count (default 1); tests tagged @exclusive run in
+// `<project>-exclusive` twins after the others (see playwright.extensions.ts).
 const baseURL = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const workers = e2eWorkers();
 const coreProjects = [
   { name: "api", testMatch: /.*\.api\.spec\.ts/ },
   { name: "ui", testMatch: /.*\.ui\.spec\.ts/, use: { ...devices["Desktop Chrome"] } },
@@ -16,12 +19,13 @@ export default defineConfig({
   fullyParallel: true,
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 2 : 0,
-  workers: process.env.CI ? 1 : undefined,
+  workers,
+  globalSetup: "./playwright.extensions.ts",
   reporter: [["list"], ["html", { open: "never" }]],
   use: {
     baseURL,
     trace: "on-first-retry",
     screenshot: "only-on-failure",
   },
-  projects: [...coreProjects, ...loadPlaywrightProjects(coreProjects)],
+  projects: withExclusivePhase([...coreProjects, ...loadPlaywrightProjects(coreProjects)], workers),
 });

package/dist/templates/fullstack/tests/playwright.extensions.ts

@@ -1,17 +1,33 @@
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join } from "node:path";
-import type { PlaywrightTestConfig } from "@playwright/test";
+import type { FullConfig, PlaywrightTestConfig } from "@playwright/test";
 
 type Projects = NonNullable<PlaywrightTestConfig["projects"]>;
+type Project = Projects[number];
 
 const requireFromTests = createRequire(__filename);
 
+// A test that changes state the other tests rely on, such as a server-wide
+// setting or the profile of a seeded account, takes the `@exclusive` tag:
+//
+//   test("maintenance mode holds visitors back", { tag: "@exclusive" }, async ({ page }) => { ... });
+//
+// Playwright matches project grep patterns against the title path followed by
+// the test's tags, separated by spaces.
+const TAGGED = /(?:^|\s)@exclusive(?=\s|$)/;
+const UNTAGGED = /^(?![\s\S]*(?:^|\s)@exclusive(?=\s|$))/;
+
 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;
 }
 
+function patterns(value: Project["grepInvert"]): RegExp[] {
+  if (value === undefined) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
 /**
  * Merge application-owned Playwright projects into PodoKit's managed config.
  * The optional CommonJS file stays owned so applications can add devices and
@@ -42,3 +58,74 @@ export function loadPlaywrightProjects(coreProjects: Projects): Projects {
 
   return loaded as Projects;
 }
+
+/** The number of Playwright workers: `E2E_WORKERS`, or 1 when it is unset. */
+export function e2eWorkers(value = process.env.E2E_WORKERS): number {
+  if (value === undefined || value.trim() === "") return 1;
+  const workers = Number(value);
+  if (!Number.isInteger(workers) || workers < 1) {
+    throw new Error(`E2E_WORKERS must be a whole number of at least 1, got "${value}".`);
+  }
+  return workers;
+}
+
+/**
+ * Splits each test project into one that skips tests tagged `@exclusive` and an
+ * `<name>-exclusive` twin that runs only them on one worker. Projects that
+ * another project depends on, or that tear one down, are setup and cleanup
+ * projects and stay as they are.
+ *
+ * With more than one worker the twins depend on every other test project, and
+ * each twin on the one before it, so an exclusive test never runs alongside
+ * another test. A dependency runs in full, though: a run that selects only
+ * exclusive tests, with a file, `--grep`, or `--project`, then also runs every
+ * other test first, and a test that fails there skips the exclusive tests. Use
+ * more than one worker for the whole suite. With one worker no dependency is
+ * needed, so filtered runs stay small.
+ */
+export function withExclusivePhase(projects: Projects, workers: number): Projects {
+  const support = new Set(
+    projects.flatMap((project) => [...(project.dependencies ?? []), ...(project.teardown ? [project.teardown] : [])]),
+  );
+  const tested = projects.filter((project) => !support.has(projectName(project) ?? ""));
+  const shared = new Map(
+    tested.map((project) => [project, { ...project, grepInvert: [...patterns(project.grepInvert), TAGGED] }]),
+  );
+
+  let before = [...shared.values()].map((project) => projectName(project) ?? "");
+  const twins = tested.map((project) => {
+    const name = `${projectName(project) ?? ""}-exclusive`;
+    const twin: Project = {
+      ...project,
+      name,
+      grepInvert: [...patterns(project.grepInvert), UNTAGGED],
+      workers: 1,
+      dependencies: workers > 1 ? [...(project.dependencies ?? []), ...before] : project.dependencies,
+    };
+    before = [name];
+    return twin;
+  });
+
+  const result = [...projects.map((project) => shared.get(project) ?? project), ...twins];
+  const names = new Set<string>();
+  for (const project of result) {
+    const name = projectName(project) ?? "";
+    if (names.has(name)) throw new Error(`Duplicate Playwright project name: ${name}`);
+    names.add(name);
+  }
+  return result;
+}
+
+/**
+ * Global setup: refuses more workers than `E2E_WORKERS` allows for. `--workers`
+ * changes the count after the projects were built, so with it the exclusive
+ * twins would run alongside the other tests.
+ */
+export default function checkWorkers(config: FullConfig): void {
+  if (config.workers > 1 && e2eWorkers() === 1) {
+    throw new Error(
+      `Set the worker count with E2E_WORKERS=${config.workers} instead of --workers. ` +
+        "Tests tagged @exclusive run after the others only when E2E_WORKERS is above 1.",
+    );
+  }
+}

package/dist/templates/fullstack/tests/ui/smoke.ui.spec.ts

@@ -1,9 +1,10 @@
 import { expect, test } from "@playwright/test";
+import { paths } from "../helpers/paths";
 
-// Module-agnostic: the app responds at "/" (a page or a redirect to it).
+// Module-agnostic: the app's first screen responds (a page or a redirect to it)
+// and renders. Its locator comes from tests/helpers/app-paths.ts.
 test("app is reachable @smoke", async ({ page }) => {
-  const res = await page.goto("/");
+  const res = await page.goto(paths.home);
   expect(res?.status()).toBeLessThan(400);
-  await expect(page.locator("main")).toBeVisible();
-  await expect(page.getByRole("heading", { level: 1 })).toBeVisible();
+  await expect(paths.homeReady(page)).toBeVisible();
 });

package/dist/templates/modules/admin-dashboard/files/apps/web/src/hooks.server.test.ts

@@ -1,5 +1,6 @@
 import { ApiError } from "@podosoft/podokit-api-client";
 import type { RequestEvent } from "@sveltejs/kit";
+import type { Handle } from "@sveltejs/kit/hooks";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { BackendUnavailableError } from "#lib/server/api.js";
 import { handle } from "./hooks.server";
@@ -14,12 +15,18 @@ const client = vi.hoisted(() => ({
   getSession: vi.fn<() => Promise<SessionResult>>(),
 }));
 
+// Stands in for the application's own hook in the app-owned app-hooks.ts.
+const appHook = vi.hoisted(() => ({
+  handle: vi.fn<Handle>(({ event, resolve }) => resolve(event)),
+}));
+vi.mock("#lib/server/app-hooks.js", () => ({ appHandle: appHook.handle }));
+
 vi.mock("#lib/server/api.js", async (importOriginal) => ({
   ...(await importOriginal<typeof import("#lib/server/api.js")>()),
   serverApiClient: () => ({ get: client.get, auth: { getSession: client.getSession } }),
 }));
 
-const resolve = vi.fn(async (): Promise<Response> => new Response("ok"));
+const resolve = vi.fn(async (_event: RequestEvent): Promise<Response> => new Response("ok"));
 
 function requestEvent(pathname: string, cookies: Record<string, string> = {}): RequestEvent {
   return {
@@ -40,6 +47,7 @@ describe("handle", () => {
     client.get.mockReset();
     client.getSession.mockReset();
     resolve.mockClear();
+    appHook.handle.mockClear();
   });
 
   it("requests the session without waiting for site settings", async () => {
@@ -144,4 +152,32 @@ describe("handle", () => {
     expect(client.getSession).not.toHaveBeenCalled();
     expect(resolve).toHaveBeenCalledTimes(1);
   });
+
+  it("runs the application hook with the loaded runtime context", async () => {
+    client.get.mockResolvedValue({ locale: null });
+    client.getSession.mockResolvedValue(signedIn);
+    let seenUser: unknown;
+    appHook.handle.mockImplementationOnce(({ event, resolve: next }) => {
+      seenUser = event.locals.user;
+      event.locals.user = { id: "local", email: "local@localhost", name: "Local", role: "admin" };
+      return next(event);
+    });
+    const event = requestEvent("/account");
+
+    const response = await handle({ event, resolve });
+
+    expect(seenUser).toEqual({ id: "user-1" });
+    expect(resolve).toHaveBeenCalledTimes(1);
+    expect(resolve.mock.calls[0]?.[0].locals.user).toMatchObject({ id: "local", role: "admin" });
+    expect(response.headers.get("x-robots-tag")).toBe("noindex, nofollow");
+  });
+
+  it("lets the application hook answer a request itself", async () => {
+    appHook.handle.mockImplementationOnce(() => new Response("teapot", { status: 418 }));
+
+    const response = await handle({ event: requestEvent("/api/site/settings"), resolve });
+
+    expect(response.status).toBe(418);
+    expect(resolve).not.toHaveBeenCalled();
+  });
 });

package/dist/templates/modules/admin-dashboard/files/apps/web/src/hooks.server.ts

@@ -3,6 +3,7 @@ import type { Handle } from "@sveltejs/kit/hooks";
 import { building } from "$app/env";
 import { routes } from "$app/manifest";
 import { serverApiClient } from "#lib/server/api.js";
+import { appHandle } from "#lib/server/app-hooks.js";
 import { resolveLocale } from "#lib/i18n/messages.js";
 import { applySearchIndexingHeaders } from "#lib/server/search-indexing.js";
 import { isPublicPath } from "#lib/server/guards.js";
@@ -91,12 +92,20 @@ export const handle: Handle = async ({ event, resolve }) => {
   } else {
     setEmptyRuntimeContext(event);
   }
-  const response = await resolve(event, {
-    transformPageChunk: ({ html }) =>
-      html.replace(
-        /(<html\b[^>]*?\slang=)(["'])[^"']*\2/i,
-        `$1"${event.locals.locale}"`,
-      ),
+  // The application's own hook from the app-owned app-hooks.ts runs next, with
+  // the runtime context loaded. Its page transform runs before the language one.
+  const response = await appHandle({
+    event,
+    resolve: (appEvent, options) =>
+      resolve(appEvent, {
+        ...options,
+        transformPageChunk: async ({ html, done }) => {
+          const transformed = options?.transformPageChunk
+            ? ((await options.transformPageChunk({ html, done })) ?? "")
+            : html;
+          return transformed.replace(/(<html\b[^>]*?\slang=)(["'])[^"']*\2/i, `$1"${event.locals.locale}"`);
+        },
+      }),
   });
   return applySearchIndexingHeaders(response, event.url.pathname);
 };

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/admin/app-flag-settings.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it, vi } from "vitest";
+import type { Messages } from "#lib/i18n/messages.js";
+import { appFlagCards } from "./app-flag-settings";
+
+// Stands in for the application's own list in the app-owned app-flags.ts.
+vi.mock("./app-flags", () => ({
+  APP_FLAG_SETTINGS: [
+    { flag: "reportsEnabled", label: () => "Reports", description: () => "Show the reports page." },
+    { flag: "betaSearch", label: () => "Beta search" },
+  ],
+}));
+
+const t = {} as Messages;
+
+describe("application flag settings", () => {
+  it("shows each listed flag with the value the API reports", () => {
+    expect(appFlagCards(t, { appFlags: { reportsEnabled: true, betaSearch: false, hidden: true } })).toEqual([
+      { flag: "reportsEnabled", name: "Reports", description: "Show the reports page.", available: true, on: true },
+      { flag: "betaSearch", name: "Beta search", description: "", available: true, on: false },
+    ]);
+  });
+
+  it("marks a flag the API does not report as unavailable", () => {
+    expect(appFlagCards(t, { appFlags: { reportsEnabled: false } })[1]).toMatchObject({
+      flag: "betaSearch",
+      available: false,
+      on: false,
+    });
+    expect(appFlagCards(t, undefined).every((card) => !card.available)).toBe(true);
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/admin/app-flag-settings.ts

@@ -0,0 +1,31 @@
+import type { Capabilities } from "@podosoft/podokit-api-client";
+import type { Messages } from "#lib/i18n/messages.js";
+import { APP_FLAG_SETTINGS } from "./app-flags";
+import type { AppFlagSetting } from "./registry.svelte.js";
+
+export type AppFlagCard = {
+  flag: string;
+  name: string;
+  description: string;
+  /** False when the API does not report the flag, for example a name missing from APP_FLAG_DEFAULTS. */
+  available: boolean;
+  on: boolean;
+};
+
+/** One card per listed flag, with the value `GET /account/capabilities` reports in `appFlags`. */
+export function appFlagCards(
+  t: Messages,
+  capabilities: Pick<Capabilities, "appFlags"> | undefined,
+  settings: readonly AppFlagSetting[] = APP_FLAG_SETTINGS,
+): AppFlagCard[] {
+  return settings.map(({ flag, label, description }) => {
+    const value = capabilities?.appFlags?.[flag];
+    return {
+      flag,
+      name: label(t),
+      description: description?.(t) ?? "",
+      available: typeof value === "boolean",
+      on: value === true,
+    };
+  });
+}

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/admin/app-flags.ts

@@ -0,0 +1,12 @@
+import type { AppFlagSetting } from "./registry.svelte.js";
+
+/**
+ * Application flags the admin Settings page shows, one switch each, on an
+ * Application tab after PodoKit's tabs. `flag` is a key of `APP_FLAG_DEFAULTS`
+ * in the API's owned `apps/api/src/settings/app-flags.ts`; the label and
+ * description come from the app-owned `i18n/catalogs/app/*.json`, for example
+ * `{ flag: "reportsEnabled", label: (t) => t.reports.flag, description: (t) => t.reports.flagDescription }`.
+ * The tab is hidden while the list is empty. PodoKit creates this file once and
+ * never overwrites it.
+ */
+export const APP_FLAG_SETTINGS: readonly AppFlagSetting[] = [];

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/admin/app-nav.ts

@@ -0,0 +1,11 @@
+import type { AdminNavEntry } from "./registry.svelte.js";
+
+/**
+ * Application-owned admin sidebar entries. The sidebar shows them after PodoKit's
+ * own pages and before module entries and Settings, for example
+ * `{ href: "/admin/reports", label: (t) => t.reports.nav, icon: ChartColumnIcon, adminOnly: true }`
+ * with the label in the app-owned `i18n/catalogs/app/*.json` and the icon from
+ * `@lucide/svelte/icons/*`. `adminOnly` hides an entry from other roles.
+ * PodoKit creates this file once and never overwrites it.
+ */
+export const APP_ADMIN_NAV: readonly AdminNavEntry[] = [];