@podosoft/podokit 0.11.2 → 0.12.0

package/dist/templates/modules/admin-dashboard/files/tests/ui/i18n.ui.spec.ts

@@ -1,13 +1,66 @@
 import { expect, test } from "@playwright/test";
-import { anonState } from "../helpers/accounts";
+import { ADMIN, adminState, anonState } from "../helpers/accounts";
 import { ready } from "../helpers/hydration";
 
 test.use({ storageState: anonState });
 
-test("language switch toggles Korean and sets <html lang>", async ({ page }) => {
+const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
+const origin = { origin: base };
+
+test("language switch updates messages and <html lang>", async ({ page }) => {
   await ready(page, "/login");
-  await page.getByRole("button", { name: "Language" }).click();
-  await page.getByRole("menuitem", { name: /한국어/ }).click();
-  await expect(page.locator("html")).toHaveAttribute("lang", "ko");
-  await expect(page.getByRole("button", { name: "로그인", exact: true })).toBeVisible();
+  const initial = await page.locator("html").getAttribute("lang");
+  await page.getByRole("button", { name: /^(Language|언어)$/ }).click();
+  if (initial === "ko") {
+    await page.getByRole("menuitem", { name: /English/ }).click();
+    await expect(page.locator("html")).toHaveAttribute("lang", "en");
+    await expect(page.getByRole("button", { name: "Sign in", exact: true })).toBeVisible();
+  } else {
+    await page.getByRole("menuitem", { name: /한국어/ }).click();
+    await expect(page.locator("html")).toHaveAttribute("lang", "ko");
+    await expect(page.getByRole("button", { name: "로그인", exact: true })).toBeVisible();
+  }
+});
+
+test("explicit English overrides a Korean site fallback", async ({ page, playwright }) => {
+  const admin = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  await admin.post("/api/auth/sign-in/email", {
+    data: { email: ADMIN.email, password: ADMIN.password },
+  });
+  const previous = await (await admin.get("/api/site/settings")).json() as { locale?: string };
+
+  try {
+    expect((await admin.put("/api/site/settings", { data: { locale: "ko" } })).ok()).toBeTruthy();
+    await page.context().addCookies([{ name: "locale", value: "en", url: base }]);
+    await ready(page, "/login");
+
+    await expect(page.locator("html")).toHaveAttribute("lang", "en");
+    await expect(page.getByRole("button", { name: "Sign in", exact: true })).toBeVisible();
+  } finally {
+    await admin.put("/api/site/settings", { data: { locale: previous.locale ?? "en" } });
+    await admin.dispose();
+  }
+});
+
+test("managed admin labels react to locale changes", async ({ browser }) => {
+  const context = await browser.newContext({ storageState: adminState });
+  const page = await context.newPage();
+
+  try {
+    await ready(page, "/admin/users");
+    const initial = await page.locator("html").getAttribute("lang");
+    if (initial === "ko") {
+      await expect(page.getByRole("columnheader", { name: "이메일" })).toBeVisible();
+      await page.getByRole("button", { name: "언어" }).click();
+      await page.getByRole("menuitem", { name: /English/ }).click();
+      await expect(page.getByRole("columnheader", { name: "Email" })).toBeVisible();
+    } else {
+      await expect(page.getByRole("columnheader", { name: "Email" })).toBeVisible();
+      await page.getByRole("button", { name: "Language" }).click();
+      await page.getByRole("menuitem", { name: /한국어/ }).click();
+      await expect(page.getByRole("columnheader", { name: "이메일" })).toBeVisible();
+    }
+  } finally {
+    await context.close();
+  }
 });

package/dist/templates/modules/admin-dashboard/files/tests/ui/login-methods.ui.spec.ts

@@ -37,5 +37,5 @@ test("login: an emailed one-time code signs a user in @smoke", async ({ page, pl
   const otp = await waitForOtp(email);
   await page.getByLabel("One-time code").fill(otp);
   await page.getByRole("button", { name: "Verify code" }).click();
-  await expect(page).toHaveURL(/\/admin/);
+  await expect(page).toHaveURL(new URL("/", base).toString());
 });

package/dist/templates/modules/admin-dashboard/files/tests/ui/passkey.ui.spec.ts

@@ -32,5 +32,5 @@ test("register a passkey and sign in with it @smoke", async ({ page, baseURL })
   await page.context().request.post("/api/auth/sign-out", { headers: origin });
   await ready(page, "/login");
   await page.getByRole("button", { name: "Use a passkey" }).click();
-  await expect(page).toHaveURL(/\/admin(\/|$)/);
+  await expect(page).toHaveURL(new URL("/", baseURL).toString());
 });

package/dist/templates/modules/admin-dashboard/files/tests/ui/settings-dialogs.ui.spec.ts

@@ -7,6 +7,7 @@ test("settings: add and remove a social login provider @smoke", async ({ page })
   const dialog = page.getByRole("dialog");
   const addBtn = dialog.getByRole("button", { name: "Add provider" });
   const openConfigure = async (): Promise<void> => {
+    await page.waitForLoadState("networkidle");
     await page.getByRole("tab", { name: "Authentication" }).click();
     await page.getByRole("button", { name: "Configure" }).click();
   };
@@ -27,12 +28,16 @@ test("settings: add and remove a social login provider @smoke", async ({ page })
   const callback = await dialog.locator("code").textContent();
   const providerId = callback?.trim().split("/").pop() ?? ""; // first addable provider (not hard-coded)
   expect(providerId).not.toBe("");
+  const expectedCallback = new URL(`/api/auth/callback/${providerId}`, page.url()).toString();
+  expect(callback?.trim()).toBe(expectedCallback);
   try {
     await dialog.locator("#social-id").fill("test-client-id");
     await dialog.locator("#social-secret").fill("test-secret");
     await dialog.getByRole("button", { name: "Save", exact: true }).click();
     // Save returns to the list view, where the new provider row has an enable switch.
     await expect(dialog.getByRole("switch").first()).toBeVisible();
+    const saved = await (await page.request.get("/api/account/auth-config")).json();
+    expect(saved.social[providerId].redirectURI).toBe(expectedCallback);
   } finally {
     if (providerId) {
       await page.request

package/dist/templates/modules/admin-dashboard/files/tests/ui/two-factor.ui.spec.ts

@@ -73,8 +73,8 @@ test("require-2fa: a new sign-up is forced through the enrolment page @smoke", a
     }).toPass({ timeout: 8000 });
     await probe.dispose();
 
-    // Signing in through the UI lands on the mandatory enrolment page.
-    await openHydratedLogin(page);
+    // Signing in toward a protected route lands on the mandatory enrolment page.
+    await openHydratedLogin(page, "/admin");
     await page.getByLabel("Email").fill(email);
     await page.getByLabel("Password").fill(pw);
     await page.getByRole("button", { name: "Sign in", exact: true }).click();

package/dist/templates/modules/admin-dashboard/module.manifest.json

@@ -13,6 +13,10 @@
     "@types/qrcode": "^1.5.5",
     "@types/multer": "^1.4.12"
   },
+  "ownedGlobs": [
+    "apps/web/src/lib/i18n/locales/**",
+    "apps/web/src/lib/i18n/catalogs/app/**"
+  ],
   "packageOverlays": {
     "api": {
       "scripts": {

package/dist/templates/modules/auth/files/apps/api/scripts/configure-auth.mjs

@@ -16,6 +16,7 @@ function usage() {
 
 Usage:
   npm run auth:configure -- --provider google --require-signup-approval
+  npm run auth:configure -- --provider google --redirect-only
   npm run auth:configure -- --smtp
   npm run auth:configure -- --check-only --provider google
 
@@ -34,6 +35,7 @@ SMTP environment (with --smtp):
 
 Options:
   --provider <id>                 Configure a social provider
+  --redirect-only                 Update only the provider callback; keep credentials and enabled state
   --smtp                          Configure SMTP from environment variables
   --require-signup-approval       Require admin approval for future registrations
   --no-require-signup-approval    Auto-approve future registrations
@@ -114,6 +116,7 @@ async function main() {
   const rawOrigin = process.env.AUTH_SETUP_ORIGIN ?? process.env.BETTER_AUTH_URL ?? "http://localhost:5002";
   const origin = new URL(rawOrigin).origin;
   const provider = value("--provider");
+  const redirectOnly = has("--redirect-only");
   const configureSmtp = has("--smtp");
   const approval = has("--require-signup-approval")
     ? true
@@ -122,8 +125,12 @@ async function main() {
       : undefined;
 
   if (provider && !/^[a-z0-9-]+$/.test(provider)) throw new Error("Provider id must use lowercase letters, numbers, or hyphens.");
+  if (redirectOnly && !provider) throw new Error("--redirect-only requires --provider <id>.");
 
-  if (provider) console.log(`OAuth callback URL: ${origin}/api/auth/callback/${provider}`);
+  const redirectURI = provider
+    ? process.env.OAUTH_REDIRECT_URI ?? `${origin}/api/auth/callback/${provider}`
+    : undefined;
+  if (redirectURI) console.log(`OAuth callback URL: ${redirectURI}`);
   if (has("--check-only")) {
     const capabilities = await publicCapabilities(origin);
     console.log(JSON.stringify(capabilities, null, 2));
@@ -135,16 +142,20 @@ async function main() {
 
   const body = {};
   if (provider) {
-    const clientId = process.env.OAUTH_CLIENT_ID ?? process.env[providerEnvName(provider, "CLIENT_ID")];
-    const clientSecret = process.env.OAUTH_CLIENT_SECRET ?? process.env[providerEnvName(provider, "CLIENT_SECRET")];
-    body.social = {
-      [provider]: {
-        enabled: true,
-        clientId: required("OAUTH_CLIENT_ID", clientId),
-        clientSecret: required("OAUTH_CLIENT_SECRET", clientSecret),
-        ...(process.env.OAUTH_REDIRECT_URI ? { redirectURI: process.env.OAUTH_REDIRECT_URI } : {}),
-      },
-    };
+    if (redirectOnly) {
+      body.social = { [provider]: { redirectURI } };
+    } else {
+      const clientId = process.env.OAUTH_CLIENT_ID ?? process.env[providerEnvName(provider, "CLIENT_ID")];
+      const clientSecret = process.env.OAUTH_CLIENT_SECRET ?? process.env[providerEnvName(provider, "CLIENT_SECRET")];
+      body.social = {
+        [provider]: {
+          enabled: true,
+          clientId: required("OAUTH_CLIENT_ID", clientId),
+          clientSecret: required("OAUTH_CLIENT_SECRET", clientSecret),
+          redirectURI,
+        },
+      };
+    }
   }
   if (configureSmtp) {
     body.smtp = {

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.ts

@@ -3,7 +3,7 @@ import { APIError } from "better-auth/api";
 import { twoFactor, haveIBeenPwned, magicLink, emailOTP, username, multiSession, phoneNumber, organization, jwt, bearer } from "better-auth/plugins";
 import { actionEmail, sendMail } from "../mail/mailer";
 import { sendSms } from "../sms/sms";
-import { createFeatureGate } from "./feature-gate";
+import { assertUserCreationAllowed, createFeatureGate, createSignupOpenCheck } from "./feature-gate";
 import { orgAc, orgRoles } from "./org-permissions";
 import { pool } from "./db";
 import { type AuthConfig, envAuthConfig, SUPPORTED_PROVIDER_IDS } from "@podosoft/podokit-auth";
@@ -44,6 +44,7 @@ function buildSocial(config: AuthConfig): NonNullable<BetterAuthOptions["socialP
 // server-enforced toggles) apply without a restart. Everything below the injection
 // markers is contributed by other PodoKit modules (admin-dashboard, audit-log).
 export function buildAuth(config: AuthConfig) {
+  const isSignupOpen = createSignupOpenCheck(pool);
   const plugins: BetterAuthPlugin[] = [
     twoFactor(),
     magicLink({
@@ -130,6 +131,7 @@ export function buildAuth(config: AuthConfig) {
         before: async (user, context) => {
           const adminEmail = adminEmails.has(user.email.toLowerCase());
           const createdByAdmin = context?.path === "/admin/create-user";
+          assertUserCreationAllowed(await isSignupOpen(), context?.path);
           return {
             data: {
               ...user,
@@ -168,7 +170,9 @@ export function buildAuth(config: AuthConfig) {
   // Request-time hooks. The feature gate turns the admin Settings toggles into a
   // real server boundary (disabled features 404). Other PodoKit modules add their
   // own hooks below the marker.
-  const hooks: NonNullable<BetterAuthOptions["hooks"]> = { before: createFeatureGate(pool) };
+  const hooks: NonNullable<BetterAuthOptions["hooks"]> = {
+    before: createFeatureGate(pool, isSignupOpen),
+  };
   // podokit:begin:auth-hooks
   // podokit:end:auth-hooks
 

package/dist/templates/modules/auth/files/apps/api/src/auth/feature-gate.ts

@@ -2,6 +2,8 @@ import { APIError, createAuthMiddleware } from "better-auth/api";
 import type { Pool } from "pg";
 import { FLAG_DEFAULTS, type FeatureFlag } from "../settings/flag-defaults";
 
+export const PUBLIC_SIGNUP_DISABLED = "PUBLIC_SIGNUP_DISABLED" as const;
+
 /** Auth-relative path prefixes owned by each admin-toggleable feature. A path is
  *  gated when it equals a prefix or starts with a prefix ending in "/". */
 const FEATURE_PATHS: Array<{ flag: FeatureFlag; prefixes: string[] }> = [
@@ -19,12 +21,55 @@ const FEATURE_PATHS: Array<{ flag: FeatureFlag; prefixes: string[] }> = [
 
 const CACHE_TTL_MS = 3_000;
 
+export type SignupOpenCheck = () => Promise<boolean>;
+
+/** Public registration is the default until an administrator explicitly closes
+ *  it. The short cache keeps every auth flow on the same live site-setting
+ *  policy without rebuilding the Better Auth instance. */
+export function createSignupOpenCheck(pool: Pool): SignupOpenCheck {
+  let signupOpen = true;
+  let fetchedAt = 0;
+
+  return async (): Promise<boolean> => {
+    if (Date.now() - fetchedAt < CACHE_TTL_MS) return signupOpen;
+    try {
+      const res = await pool.query<{ value: string }>(
+        'SELECT "value" FROM "app_setting" WHERE "key" = $1',
+        ["site.allowSignup"],
+      );
+      signupOpen = res.rows[0]?.value !== "false";
+    } catch {
+      signupOpen = true;
+    }
+    fetchedAt = Date.now();
+    return signupOpen;
+  };
+}
+
+/** Administrator-created users are intentional and remain available when the
+ *  public site is invite-only. Every other new-user path, including OAuth
+ *  callbacks, must follow the public registration setting. */
+export function isUserCreationAllowed(signupOpen: boolean, requestPath?: string): boolean {
+  return signupOpen || requestPath === "/admin/create-user";
+}
+
+export function assertUserCreationAllowed(signupOpen: boolean, requestPath?: string): void {
+  if (isUserCreationAllowed(signupOpen, requestPath)) return;
+  throw APIError.from("FORBIDDEN", {
+    code: PUBLIC_SIGNUP_DISABLED,
+    message: "Public sign-up is disabled.",
+  });
+}
+
 /** Server-side enforcement for the admin Settings toggles: requests to a disabled
  *  feature's endpoints are rejected with 404, so "off" is a real boundary rather
  *  than hidden UI. Flags are read from app_setting through a small TTL cache
  *  (a toggle takes effect within ~CACHE_TTL_MS); before the migration has run,
  *  the shipped defaults apply. */
-export function createFeatureGate(pool: Pool) {
+export function createFeatureGate(
+  pool: Pool,
+  isSignupOpen: SignupOpenCheck = createSignupOpenCheck(pool),
+) {
   let cache: Record<FeatureFlag, boolean> = { ...FLAG_DEFAULTS };
   let fetchedAt = 0;
 
@@ -45,32 +90,12 @@ export function createFeatureGate(pool: Pool) {
     return cache;
   }
 
-  // Registration can be closed from the admin Settings ("Allow sign-up"). It is a
-  // site setting (`site.allowSignup`), so the row is absent until an admin turns
-  // it off — a missing/any-non-"false" value means open, matching the shipped
-  // default. Cached the same way as the feature flags.
-  let signupOpen = true;
-  let signupFetchedAt = 0;
-  async function isSignupOpen(): Promise<boolean> {
-    if (Date.now() - signupFetchedAt < CACHE_TTL_MS) return signupOpen;
-    try {
-      const res = await pool.query<{ value: string }>(
-        'SELECT "value" FROM "app_setting" WHERE "key" = $1',
-        ["site.allowSignup"],
-      );
-      signupOpen = res.rows[0]?.value !== "false";
-    } catch {
-      signupOpen = true;
-    }
-    signupFetchedAt = Date.now();
-    return signupOpen;
-  }
-
   return createAuthMiddleware(async (ctx) => {
-    // Block email/password registration when sign-up is closed. Social/invite
-    // flows are unaffected; admins create users from the dashboard.
+    // Reject explicit sign-up endpoints early. OAuth starts remain available so
+    // existing social users can sign in; their new-user callback is enforced by
+    // the database hook that uses this same policy.
     if (ctx.path === "/sign-up/email" || ctx.path.startsWith("/sign-up/")) {
-      if (!(await isSignupOpen())) throw new APIError("FORBIDDEN", { message: "Sign-up is disabled." });
+      assertUserCreationAllowed(await isSignupOpen(), ctx.path);
       return;
     }
     const feature = FEATURE_PATHS.find((f) =>

package/dist/templates/modules/auth/files/dot-claude/skills/podokit-configure-auth/SKILL.md

@@ -26,7 +26,7 @@ Use the generated `auth:configure` command so credentials enter the encrypted `a
    ```
 
 4. Create or verify the initial administrator with `admin:bootstrap` before enabling mandatory email verification or other runtime authentication settings.
-5. Derive the default callback as `<BETTER_AUTH_URL>/api/auth/callback/<provider>`. Only set `OAUTH_REDIRECT_URI` when the provider requires an explicit override.
+5. Derive the default callback as `<BETTER_AUTH_URL>/api/auth/callback/<provider>`. Only set `OAUTH_REDIRECT_URI` when the provider requires an explicit override. If credentials are already stored, use `--provider <id> --redirect-only` to update the callback without reading or replacing the client secret.
 
 ## Handle secrets safely
 

package/dist/templates/modules/auth/files/dot-claude/skills/podokit-configure-auth/references/google.md

@@ -12,8 +12,52 @@ Use a Google Cloud project owned by the organization, not a personal project.
 
 Google may require verification for an External production app, especially when sensitive scopes or branding are involved. Keep the homepage, privacy policy, terms, and verified domain consistent with the OAuth consent screen.
 
+## Development
+
+Keep normal development on the portless `*.localhost` origin provided by `podo dev`.
+For an actual OAuth round trip, expose the web container through a stable HTTPS
+development hostname using a Cloudflare Named Tunnel, a reserved ngrok domain, or a
+preview deployment. Use a separate Google Cloud project and Web client for development.
+
+1. Add `https://app-dev.example.com` as an authorized JavaScript origin.
+2. Add `https://app-dev.example.com/api/auth/callback/google` as the exact redirect URI.
+3. Include both `http://app.localhost` and `https://app-dev.example.com` in
+   `CORS_ORIGIN`. Use the HTTPS origin as `BETTER_AUTH_URL` for the tunnel profile.
+4. Open Admin Settings through the HTTPS origin before saving Google. The displayed
+   callback is persisted. With the CLI, `AUTH_SETUP_ORIGIN` derives and persists the
+   same callback; set `OAUTH_REDIRECT_URI` only for an explicit override. Configure
+   without putting the secret on the command line:
+
+   ```bash
+   export AUTH_SETUP_ORIGIN="https://app-dev.example.com"
+   export AUTH_SETUP_ADMIN_EMAIL="admin@example.com"
+   export AUTH_SETUP_ADMIN_PASSWORD="<from-secret-manager>"
+   export OAUTH_CLIENT_ID="<google-client-id>"
+   export OAUTH_CLIENT_SECRET="<from-secret-manager>"
+   npm run auth:configure -w <app>-api -- --provider google --dry-run
+   npm run auth:configure -w <app>-api -- --provider google
+   ```
+
+   If only an existing callback is stale, keep the stored client ID, client
+   secret, and enabled state:
+
+   ```bash
+   AUTH_SETUP_ORIGIN=https://app-dev.example.com \
+     npm run auth:configure -w <app>-api -- --provider google --redirect-only
+   ```
+
+5. Start and finish Google sign-in through the HTTPS origin. Do not mix it with
+   `app.localhost`; OAuth state cookies are scoped to the origin that created them.
+
+Protect development content with the tunnel provider's access control, but bypass
+the exact `/api/auth/callback/*` path so Google can reach it. Quick tunnels with a
+changing hostname are unsuitable for a registered callback. See the PodoKit
+`docs/oauth-development.md` guide for the provider-neutral boundary.
+
 Official references:
 
 - https://developers.google.com/identity/protocols/oauth2/web-server
 - https://developers.google.com/identity/protocols/oauth2/policies
+- https://support.google.com/cloud/answer/15549257
 - https://better-auth.com/docs/authentication/google
+- https://better-auth.com/docs/plugins/oauth-proxy

package/dist/templates/todo/README.md

@@ -8,10 +8,49 @@ Full-stack TypeScript app generated with [PodoKit](https://github.com/podosoft-d
 
 ## Getting started
 
+### Recommended: containerized development
+
 ```bash
 {{packageManager}} install
 cp .env.example .env
+npx @podosoft/podokit dev watch
+```
+
+Open the URL printed by the command; a new project defaults to
+**http://{{projectName}}.localhost**. The committed `.podokit/dev.json` is the
+source of truth if you change the hostname. The first running PodoKit project starts
+one user-level Traefik gateway on `127.0.0.1:80`; additional projects reuse it and
+route by that hostname. Even a single app uses
+the same topology, with one route and no project-specific host port.
+
+In a second terminal, apply the included Todo migration and use the lifecycle helpers:
+
+```bash
+npx @podosoft/podokit dev exec api npm run migration:run -w {{projectName}}-api
+npx @podosoft/podokit dev url
+npx @podosoft/podokit dev ps
+npx @podosoft/podokit dev logs
+npx @podosoft/podokit dev down
+```
+
+If installed modules require extra services, use their profiles on the initial
+watch command instead:
 
+```bash
+npx @podosoft/podokit dev watch \
+  --profile cache --profile storage --profile queue
+```
+
+Pass the same profile flags to other lifecycle commands when applicable. `dev down`
+removes this project's stack and route. If it is the final registered
+project, it also removes the shared gateway and network. Source changes are synced
+through Compose Watch, including Vite HMR on the same portless browser origin.
+
+### Alternative: host processes
+
+Use this loop when you want only the web and API processes on the host:
+
+```bash
 # start local PostgreSQL + Redis
 docker compose -f infra/docker/docker-compose.yml up -d
 
@@ -25,6 +64,9 @@ docker compose -f infra/docker/docker-compose.yml up -d
 - API: http://localhost:5002 — health at `/health`, docs at `/api-docs`
 - Web: http://localhost:5001
 
+For multi-project routing, container profiles, and OAuth over a stable HTTPS
+tunnel, see the PodoKit [development guide](https://github.com/podosoft-dev/podokit/blob/main/docs/development.md).
+
 ## Database & migrations
 
 The API uses TypeORM with PostgreSQL. A sample `Todo` entity and an initial migration are included — replace them with your own domain model.

package/dist/templates/todo/apps/web/src/lib/i18n/README.md

@@ -1,7 +1,9 @@
-# i18n
+# Localization
 
-Locales use [typesafe-i18n](https://github.com/ivanhofer/typesafe-i18n).
+Locale definitions live in `locales/<code>.json`. Product copy and intentional
+module overrides live in the app-owned `catalogs/app/<code>.json` files.
 
-- `en.ts` is the base locale; `ko.ts` mirrors its shape.
-- Run `npx typesafe-i18n` to generate the typed runtime and Svelte store,
-  then use `$LL.appTitle()` in components. Add keys to every locale.
+The admin-dashboard module installs the composed JSON message runtime and its
+complete English and Korean catalogs. Use `podo locale add`, `validate`, and
+`activate` to extend it. See the generated `$podokit-add-locale` skill for the
+complete workflow.

package/dist/templates/todo/apps/web/src/lib/i18n/catalogs/app/en.json

@@ -0,0 +1 @@
+{}

package/dist/templates/todo/apps/web/src/lib/i18n/catalogs/app/ko.json

@@ -0,0 +1 @@
+{}

package/dist/templates/todo/apps/web/src/lib/i18n/locales/en.json

@@ -0,0 +1,6 @@
+{
+  "code": "en",
+  "name": "English",
+  "direction": "ltr",
+  "enabled": true
+}

package/dist/templates/todo/apps/web/src/lib/i18n/locales/ko.json

@@ -0,0 +1,6 @@
+{
+  "code": "ko",
+  "name": "한국어",
+  "direction": "ltr",
+  "enabled": true
+}

package/dist/templates/todo/apps/web/vite.config.ts

@@ -2,15 +2,10 @@ import { sveltekit } from "@sveltejs/kit/vite";
 import tailwindcss from "@tailwindcss/vite";
 import { defineConfig } from "vite";
 
-// Inside the dev container (compose.dev.yaml sets VITE_DOCKER=1): bind to all
-// interfaces, allow the Traefik hostname, and route HMR's WebSocket back through
-// Traefik. The browser reaches the app at Traefik's published host port, so the
-// HMR client must target that same port — otherwise the ws connects to :80,
-// fails, and Vite silently falls back to a full page reload on every change
-// (which wipes in-progress form input). compose.dev.yaml injects
-// VITE_HMR_CLIENT_PORT to match the published Traefik port (default 80).
+// Inside the dev container, bind to all interfaces and accept local gateway or
+// HTTPS tunnel hostnames. Vite derives HMR's protocol, host, and port from the
+// browser origin so the same configuration works for both entry points.
 const inDocker = process.env.VITE_DOCKER === "1";
-const hmrClientPort = Number(process.env.VITE_HMR_CLIENT_PORT) || 80;
 
 export default defineConfig({
   plugins: [tailwindcss(), sveltekit()],
@@ -19,7 +14,6 @@ export default defineConfig({
         host: true,
         port: 5001,
         allowedHosts: true,
-        hmr: { clientPort: hmrClientPort },
       }
     : undefined,
 });

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

@@ -1,13 +1,11 @@
 # Containerized development environment.
 #
-#   docker compose -f compose.dev.yaml watch                       # core stack
-#   docker compose -f compose.dev.yaml --profile cache \
-#     --profile storage --profile queue watch                     # with modules
+#   podo dev watch                                                # core stack
+#   podo dev watch --profile cache --profile storage \
+#     --profile queue                                             # with modules
 #
-# Only Traefik binds a host port (default 80). The app is at http://app.localhost.
-# Set TRAEFIK_PORT to publish on another port (e.g. TRAEFIK_PORT=8001) so several
-# containerized stacks can run at once without colliding — the web container reads
-# the same value as VITE_HMR_CLIENT_PORT so Vite HMR follows automatically.
+# 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.
 #
@@ -24,6 +22,7 @@ name: {{projectName}}-dev
 
 services:
   traefik:
+    profiles: [podokit-legacy-proxy]
     image: traefik:v3.5
     command:
       - --providers.file.filename=/etc/traefik/dynamic.yml
@@ -52,10 +51,6 @@ services:
       # getClientAddress() tied to the visitor instead of the proxy container.
       - ADDRESS_HEADER=x-forwarded-for
       - XFF_DEPTH=1
-      # Match Traefik's published port so HMR's WebSocket targets the right port
-      # (default 80). Without this, HMR connects to :80 and a non-80 stack falls
-      # back to a full page reload on every edit.
-      - VITE_HMR_CLIENT_PORT=${TRAEFIK_PORT:-80}
     depends_on: [api]
     networks: [podokit]
     develop:

package/dist/templates/todo/dot-claude/skills/podokit-add-locale/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: podokit-add-locale
+description: Add, translate, validate, activate, or troubleshoot a JSON locale in a PodoKit-generated SvelteKit app. Use when a user asks to add a language, split or edit locale JSON, check translation coverage or placeholders, configure fallback behavior, or verify locale changes through Vite HMR.
+---
+
+# PodoKit Add Locale
+
+Add languages through the PodoKit locale commands and the app-owned JSON catalog. Keep module catalogs managed so `podo update` can continue to update them.
+
+## Workflow
+
+1. Inspect the existing locale state.
+
+   ```sh
+   podo locale list
+   ```
+
+2. Add a canonical BCP 47 language tag. Set `--direction rtl` only for right-to-left languages.
+
+   ```sh
+   podo locale add pt-BR --name "Português (Brasil)"
+   ```
+
+3. Read [references/catalog-format.md](references/catalog-format.md), then translate the new app-owned file at `apps/web/src/lib/i18n/catalogs/app/<locale>.json`.
+
+4. Validate key coverage, JSON value types, and interpolation placeholders.
+
+   ```sh
+   podo locale validate pt-BR
+   ```
+
+5. Activate the locale. Partial catalogs are permitted because runtime fallback fills missing keys, but report the coverage percentage to the user.
+
+   ```sh
+   podo locale activate pt-BR
+   ```
+
+6. Run the app with its documented container-based development command. Verify the language switch, one complete key, one fallback key, and locale persistence. Editing an existing JSON file must update through Vite HMR without restarting the container. Adding a new locale file may trigger an automatic full-page reload.
+
+## Rules
+
+- Treat `en` as the stable final fallback and never deactivate it.
+- Preserve placeholders exactly. For example, translate `Hello {name}` without renaming or removing `{name}`.
+- Put product-specific copy only in `catalogs/app/`. Do not edit `catalogs/admin-dashboard/` or other module catalogs directly.
+- Keep locale definition filenames identical to their canonical codes, including case such as `pt-BR.json`.
+- Do not activate a locale definition before its JSON parses and `podo locale validate` succeeds.
+- Do not use the UI message catalogs for user-authored records. Dynamic content needs locale-aware records and a separate publication/fallback policy.
+- When deactivating a locale, preserve its files so it can be reactivated without losing translations.
+
+## Fallback And Site Default
+
+The message runtime resolves missing keys in this order: selected locale, configured site default, then English. The site default is an administrator choice, not a build-time constant. Changing it must not delete or rewrite catalogs.
+
+If a requested language is unsupported or inactive, resolve it to the configured site default. Keep localized URL and SEO behavior in the consuming app; the catalogs provide translated strings but do not define routing policy.
+
+## Completion Checklist
+
+- `podo locale validate` succeeds for every active locale.
+- The new locale definition is active and has the intended display name and direction.
+- App-owned JSON contains the new product copy; managed module catalogs remain untouched.
+- Development edits update without a container restart.
+- Automated tests cover selection, fallback, placeholders, and at least one incomplete catalog.
+- User-facing locale setup or routing documentation is updated when behavior changes.

package/dist/templates/todo/dot-claude/skills/podokit-add-locale/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "PodoKit Locale Setup"
+  short_description: "Add and validate JSON locale catalogs safely"
+  default_prompt: "Use $podokit-add-locale to add, validate, activate, and test a new JSON locale in this PodoKit app."