@podosoft/podokit 0.11.1 → 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,17 @@
     "@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": {
+        "admin:bootstrap": "node scripts/bootstrap-admin.mjs"
+      }
+    }
+  },
   "env": [
     "# admin-dashboard: emails auto-promoted to the admin role on sign-up (comma-separated)",
     "ADMIN_EMAILS=admin@example.com"
@@ -42,7 +53,7 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### admin-dashboard\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Emails in `ADMIN_EMAILS` become admins on sign-up. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- **Every list/table MUST use the shared `$lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `$lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand.\n"
+      "text": "### admin-dashboard\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `npm run admin:bootstrap -w <app>-api`; never commit or persist `ADMIN_BOOTSTRAP_PASSWORD`. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- **Every list/table MUST use the shared `$lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `$lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand.\n"
     },
     {
       "file": "apps/api/src/app.module.ts",
@@ -56,9 +67,9 @@
     }
   ],
   "instructions": [
-    "Set ADMIN_EMAILS in .env (comma-separated). Those emails become admins on sign-up.",
+    "Set ADMIN_EMAILS in .env (comma-separated). After building and migrating, inject ADMIN_BOOTSTRAP_EMAIL and ADMIN_BOOTSTRAP_PASSWORD for one command only, then run npm run admin:bootstrap -w <app>-api. The command creates a verified, approved admin or safely verifies an existing one.",
     "Re-run the auth migration to add the admin and sign-up approval columns:  npx @better-auth/cli migrate -y --config apps/api/src/auth/auth.ts",
-    "Start the app (npm run dev), open /signup, register an ADMIN_EMAILS address, then sign in.",
+    "Remove ADMIN_BOOTSTRAP_PASSWORD from the environment after bootstrap. Keep ADMIN_EMAILS so matching future sign-ups are promoted consistently.",
     "Admin pages: /admin/users (list, approve pending registrations, ban, set role, revoke sessions). Signed-in users manage their profile and security at /account; /admin/account remains available in the admin shell. Admin, account, authentication, maintenance, and API responses include X-Robots-Tag: noindex, nofollow by default.",
     "Password reset emails go through the mailer module (installed automatically with auth); in dev without SMTP they are logged to the API console. Configure SMTP in admin settings or via SMTP_* env for production."
   ]

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

@@ -1,6 +1,6 @@
 ---
 name: podokit-configure-auth
-description: Configure and verify PodoKit social OAuth providers, SMTP delivery, and the administrator sign-up approval policy. Use when enabling Google, Apple, or another Better Auth provider; calculating callback URLs; applying credentials through Admin Settings; configuring outbound mail; or diagnosing why a configured sign-in method is unavailable.
+description: Bootstrap and verify the initial PodoKit administrator, then configure social OAuth providers, SMTP delivery, and sign-up approval. Use when setting the first admin email/password; enabling Google, Apple, or another Better Auth provider; calculating callback URLs; applying credentials through Admin Settings; configuring outbound mail; or diagnosing unavailable sign-in methods.
 ---
 
 # Configure PodoKit authentication
@@ -12,6 +12,7 @@ Use the generated `auth:configure` command so credentials enter the encrypted `a
 - Read [references/google.md](references/google.md) for Google sign-in, including External audience requirements.
 - Read [references/apple.md](references/apple.md) for Apple sign-in and client-secret rotation.
 - Read [references/smtp.md](references/smtp.md) for Google Workspace SMTP relay and DNS authentication.
+- Read [references/bootstrap-admin.md](references/bootstrap-admin.md) before creating or repairing access to the first administrator.
 - Run the same generated command for other provider IDs. Confirm the provider appears in Admin Settings before applying it.
 
 ## Prepare the app
@@ -24,7 +25,8 @@ Use the generated `auth:configure` command so credentials enter the encrypted `a
    npm run migrate:all -w <app>-api
    ```
 
-4. Derive the default callback as `<BETTER_AUTH_URL>/api/auth/callback/<provider>`. Only set `OAUTH_REDIRECT_URI` when the provider requires an explicit override.
+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. If credentials are already stored, use `--provider <id> --redirect-only` to update the callback without reading or replacing the client secret.
 
 ## Handle secrets safely
 
@@ -44,6 +46,17 @@ export OAUTH_CLIENT_SECRET
 export OAUTH_CLIENT_ID="provider-client-id"
 ```
 
+The bootstrap command accepts the same `AUTH_SETUP_ADMIN_EMAIL` and
+`AUTH_SETUP_ADMIN_PASSWORD` variables as fallbacks. Keep `ADMIN_EMAILS` in the
+deployment environment, run the bootstrap once, and reuse the ephemeral
+credentials for `auth:configure`:
+
+```bash
+export ADMIN_EMAILS="admin@example.com"
+npm run admin:bootstrap -w <app>-api -- --dry-run
+npm run admin:bootstrap -w <app>-api
+```
+
 Unset sensitive variables when finished:
 
 ```bash

package/dist/templates/modules/auth/files/dot-claude/skills/podokit-configure-auth/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "PodoKit Auth Setup"
-  short_description: "Configure social login, SMTP, and signup approval"
-  default_prompt: "Use $podokit-configure-auth to configure Google login, SMTP, and sign-up approval safely."
+  short_description: "Bootstrap admin and configure authentication safely"
+  default_prompt: "Use $podokit-configure-auth to bootstrap the first administrator, then configure Google login, SMTP, and sign-up approval safely."

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

@@ -0,0 +1,51 @@
+# Bootstrap the initial administrator
+
+Use the generated database-backed command after the API build and migrations.
+Do not create the first administrator through the public sign-up page.
+
+## Set the persistent allowlist
+
+Set `ADMIN_EMAILS` in the same deployment environment used by the API. Include
+the exact lowercase-normalized address selected for the initial administrator.
+Keep this value after bootstrap so future matching sign-ups retain the same role
+policy.
+
+## Inject credentials for one command
+
+Prefer the deployment secret manager or a hidden shell prompt. Do not put the
+password in a command argument, repository file, image layer, CI log, or
+long-lived Kubernetes Secret.
+
+```bash
+export ADMIN_BOOTSTRAP_EMAIL="admin@example.com"
+printf "Initial admin password: " >&2
+IFS= read -r -s ADMIN_BOOTSTRAP_PASSWORD
+printf "\n" >&2
+export ADMIN_BOOTSTRAP_PASSWORD
+```
+
+`AUTH_SETUP_ADMIN_EMAIL` and `AUTH_SETUP_ADMIN_PASSWORD` are accepted as
+fallbacks so the same ephemeral values can immediately configure OAuth and SMTP.
+
+## Preview, create, and verify
+
+```bash
+npm run admin:bootstrap -w <app>-api -- --dry-run
+npm run admin:bootstrap -w <app>-api
+npm run admin:bootstrap -w <app>-api -- --check-only
+```
+
+The create path writes `role=admin`, `emailVerified=true`, and
+`signupApproved=true`. A rerun never updates an existing row or resets a
+password. It succeeds only when the account still has the admin role, verified
+and approved flags, and the supplied password matches.
+
+Unset the password immediately after `auth:configure` or the verification step:
+
+```bash
+unset ADMIN_BOOTSTRAP_PASSWORD AUTH_SETUP_ADMIN_PASSWORD
+```
+
+If the command reports an existing mismatched account, stop. Recover it through
+an authenticated administrator or an audited operator procedure; do not delete,
+promote, verify, or reset the row automatically.

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/modules/auth/module.manifest.json

@@ -3,6 +3,9 @@
   "description": "Full authentication (better-auth): email/password, sessions, and \u2014 via config \u2014 OAuth and 2FA. Installs a global guard so the API is secure by default; health and /api/auth stay public.",
   "requires": ["mailer"],
   "targetApp": "api",
+  "managedOverrides": [
+    ".claude/skills/podokit-configure-auth/**"
+  ],
   "dependencies": {
     "@podosoft/podokit-auth": "^0.2.0",
     "@podosoft/podokit-contracts": "^0.2.0",

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/api/Dockerfile

@@ -20,6 +20,7 @@ RUN addgroup -S app && adduser -S app -G app
 COPY --from=build /app/node_modules ./node_modules
 COPY --from=deps /app/apps/api ./apps/api
 COPY --from=build /app/apps/api/dist ./apps/api/dist
+COPY --from=build /app/apps/api/scripts ./apps/api/scripts
 WORKDIR /app/apps/api
 USER app
 EXPOSE 3000

package/dist/templates/todo/apps/api/scripts/.keep

@@ -0,0 +1 @@
+

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 @@
+{}